@mlx-node/core 0.0.8 → 0.0.9

package/index.d.cts

@@ -195,50 +195,24 @@ export declare class Gemma4Model {
   /**
    * Start a new chat session.
    *
-   * Runs the full jinja chat template once, decodes until the
-   * family's session stop token, and leaves the KV caches on a
-   * clean turn boundary so subsequent `chatSessionContinue` /
-   * `chatSessionContinueTool` calls can append a raw delta on
-   * top without re-rendering the chat template.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw user/assistant delta to the session's cached
-   * KV state, then decodes the assistant reply, stopping on the
-   * family's session boundary token.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the
-   * native side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can route image-changes back through a
-   * fresh `chatSessionStart`.
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds the family's tool-result delta from `content` and
-   * prefills it on top of the live session caches, then decodes
-   * the assistant reply.
-   *
-   * `is_error` is the structured tool-error signal. When
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
-   * rendered tool block.
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-    isError?: boolean | undefined | null,
-  ): Promise<ChatResult>;
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -247,26 +221,15 @@ export declare class Gemma4Model {
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * `is_error` mirrors the non-streaming entry point — when
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
-   * tool block.
-   */
+  /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
 }
 
@@ -553,50 +516,24 @@ export declare class Lfm2Model {
   /**
    * Start a new chat session.
    *
-   * Runs the full jinja chat template once, decodes until the
-   * family's session stop token, and leaves the KV caches on a
-   * clean turn boundary so subsequent `chatSessionContinue` /
-   * `chatSessionContinueTool` calls can append a raw delta on
-   * top without re-rendering the chat template.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw user/assistant delta to the session's cached
-   * KV state, then decodes the assistant reply, stopping on the
-   * family's session boundary token.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the
-   * native side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can route image-changes back through a
-   * fresh `chatSessionStart`.
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds the family's tool-result delta from `content` and
-   * prefills it on top of the live session caches, then decodes
-   * the assistant reply.
-   *
-   * `is_error` is the structured tool-error signal. When
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
-   * rendered tool block.
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-    isError?: boolean | undefined | null,
-  ): Promise<ChatResult>;
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -605,26 +542,15 @@ export declare class Lfm2Model {
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * `is_error` mirrors the non-streaming entry point — when
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
-   * tool block.
-   */
+  /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
 }
 
@@ -1108,11 +1034,9 @@ export declare class QianfanOCRModel {
   /**
    * Start a new chat session.
    *
-   * Runs the full chat template once, decodes until `<|im_end|>`,
-   * and leaves the KV caches on a clean turn boundary so subsequent
-   * `chatSessionContinue` / `chatSessionContinueTool` calls can
-   * append a raw ChatML delta on top without re-rendering the chat
-   * template.
+   * Renders the complete structured conversation through the checkpoint
+   * template, decodes until `<|im_end|>`, and preserves KV state for an
+   * exact-prefix check against the next complete template render.
    *
    * Qianfan-OCR is always a VLM (InternViT + Qwen3 language model), so
    * this entry point accepts images in `messages` without the text-only
@@ -1120,97 +1044,33 @@ export declare class QianfanOCRModel {
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw ChatML user/assistant delta to the session's cached
-   * KV state, then decodes the model reply. Stops on `<|im_end|>` so
-   * the cache remains on a clean turn boundary for the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`. Errors
-   * if the session is empty or if `config.reuse_cache` is
-   * explicitly set to `false`.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the native
-   * side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can catch the prefix and route image-changes
-   * back through a fresh `chatSessionStart` uniformly across all
-   * model backends. Qianfan-OCR is a VLM but the continue path cannot
-   * splice new vision features into a live KV cache — image changes
-   * always require a fresh session start.
-   *
-   * `audio` exists only to keep this method's positional ABI aligned
-   * with the shared chat surface every other family exposes (the
-   * `chat_napi_surface!` macro inserts `audio` between `images` and
-   * `config`). Qianfan-OCR has no audio support, so a non-empty
-   * `audio` is rejected at the boundary with the shared no-audio
-   * error; `None` / empty is a complete no-op and audio is never
-   * threaded into the model thread.
-   */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
-  /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds a ChatML `<tool_response>` delta from `tool_call_id` and
-   * `content` and prefills it on top of the live session caches, then
-   * decodes the model reply. Stops on `<|im_end|>` so the cache stays
-   * on a clean turn boundary for the next turn.
-   *
-   * `is_error` is the structured tool-error signal. When `Some(true)`,
-   * the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
-   * `<tool_response>` wrapper so the model receives a clear text-level
-   * cue. `None` / `Some(false)` keep the wire bytes byte-equal to the
-   * pre-feature output.
-   *
-   * Requires a live session started via `chatSessionStart`.
-   */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-    isError?: boolean | undefined | null,
-  ): Promise<ChatResult>;
+   * Continue from the caller's complete conversation history. The
+   * checkpoint's chat template is rendered again and exact prefix matching
+   * decides whether the live cache can be reused.
+   */
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Tool-result continuation over a full history. Tool representation is
+   * owned entirely by the model-provided template.
+   */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinue`.
-   *
-   * `audio` mirrors the non-streaming entry point: it exists only to
-   * keep the positional ABI aligned with the shared chat surface, and
-   * a non-empty value is rejected at the boundary with the shared
-   * no-audio error. `None` / empty is a complete no-op.
-   */
+  /** Streaming continuation over a complete conversation history. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * `is_error` mirrors the non-streaming entry point — when
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
-   * `<tool_response>` wrapper.
-   */
+  /** Streaming tool-result continuation over a complete history. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
 }
 
@@ -1303,50 +1163,24 @@ export declare class Qwen35Model {
   /**
    * Start a new chat session.
    *
-   * Runs the full jinja chat template once, decodes until the
-   * family's session stop token, and leaves the KV caches on a
-   * clean turn boundary so subsequent `chatSessionContinue` /
-   * `chatSessionContinueTool` calls can append a raw delta on
-   * top without re-rendering the chat template.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw user/assistant delta to the session's cached
-   * KV state, then decodes the assistant reply, stopping on the
-   * family's session boundary token.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the
-   * native side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can route image-changes back through a
-   * fresh `chatSessionStart`.
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds the family's tool-result delta from `content` and
-   * prefills it on top of the live session caches, then decodes
-   * the assistant reply.
-   *
-   * `is_error` is the structured tool-error signal. When
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
-   * rendered tool block.
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-    isError?: boolean | undefined | null,
-  ): Promise<ChatResult>;
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -1355,26 +1189,15 @@ export declare class Qwen35Model {
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * `is_error` mirrors the non-streaming entry point — when
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
-   * tool block.
-   */
+  /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
 }
 export type Qwen3_5Model = Qwen35Model;
@@ -1455,50 +1278,24 @@ export declare class Qwen35MoeModel {
   /**
    * Start a new chat session.
    *
-   * Runs the full jinja chat template once, decodes until the
-   * family's session stop token, and leaves the KV caches on a
-   * clean turn boundary so subsequent `chatSessionContinue` /
-   * `chatSessionContinueTool` calls can append a raw delta on
-   * top without re-rendering the chat template.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw user/assistant delta to the session's cached
-   * KV state, then decodes the assistant reply, stopping on the
-   * family's session boundary token.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the
-   * native side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can route image-changes back through a
-   * fresh `chatSessionStart`.
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds the family's tool-result delta from `content` and
-   * prefills it on top of the live session caches, then decodes
-   * the assistant reply.
-   *
-   * `is_error` is the structured tool-error signal. When
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
-   * rendered tool block.
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-    isError?: boolean | undefined | null,
-  ): Promise<ChatResult>;
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -1507,26 +1304,15 @@ export declare class Qwen35MoeModel {
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * `is_error` mirrors the non-streaming entry point — when
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
-   * tool block.
-   */
+  /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
 }
 export type Qwen3_5MoeModel = Qwen35MoeModel;
@@ -1656,50 +1442,24 @@ export declare class Qwen3Model {
   /**
    * Start a new chat session.
    *
-   * Runs the full jinja chat template once, decodes until the
-   * family's session stop token, and leaves the KV caches on a
-   * clean turn boundary so subsequent `chatSessionContinue` /
-   * `chatSessionContinueTool` calls can append a raw delta on
-   * top without re-rendering the chat template.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw user/assistant delta to the session's cached
-   * KV state, then decodes the assistant reply, stopping on the
-   * family's session boundary token.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the
-   * native side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can route image-changes back through a
-   * fresh `chatSessionStart`.
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds the family's tool-result delta from `content` and
-   * prefills it on top of the live session caches, then decodes
-   * the assistant reply.
-   *
-   * `is_error` is the structured tool-error signal. When
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
-   * rendered tool block.
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-    isError?: boolean | undefined | null,
-  ): Promise<ChatResult>;
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -1708,26 +1468,15 @@ export declare class Qwen3Model {
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    audio: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * `is_error` mirrors the non-streaming entry point — when
-   * `Some(true)`, the renderer prepends the shared
-   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
-   * tool block.
-   */
+  /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
   /**
    * Load a pretrained model from disk
@@ -1862,6 +1611,9 @@ export declare class Qwen3Tokenizer {
    * * `add_generation_prompt` - Whether to add assistant prompt at end (default: true)
    * * `tools` - Optional array of tool definitions for function calling
    * * `enable_thinking` - Optional flag to enable thinking mode (<think> tags)
+   * * `content_order` - Optional structured multimodal content ordering
+   * * `existing_image_placeholder` - Optional model marker that suppresses
+   *   synthetic image parts when it is already present in sanitized text
    *
    * # Returns
    * Encoded token IDs ready for model input
@@ -1887,6 +1639,8 @@ export declare class Qwen3Tokenizer {
     addGenerationPrompt?: boolean | undefined | null,
     tools?: Array<ToolDefinition> | undefined | null,
     enableThinking?: boolean | undefined | null,
+    contentOrder?: MultimodalContentOrder | undefined | null,
+    existingImagePlaceholder?: string | undefined | null,
   ): Promise<Uint32Array>;
   /** Get vocabulary size */
   vocabSize(): number;
@@ -2169,17 +1923,11 @@ export declare class TextRecModel {
   recognizeCrop(rgbData: Uint8Array, width: number, height: number): RecResult;
 }
 
-/** Result from VLM chat */
 export declare class VlmChatResult {
-  /** Get the response text */
   get text(): string;
-  /** Get the generated tokens */
   get tokens(): MxArray;
-  /** Get the log probabilities */
   get logprobs(): MxArray;
-  /** Get the finish reason */
   get finishReason(): 'stop' | 'length' | 'repetition';
-  /** Get the number of tokens generated */
   get numTokens(): number;
 }
 export type VLMChatResult = VlmChatResult;
@@ -2519,15 +2267,9 @@ export interface ChatMessage {
    * Authoritative, structured signal of tool-call failure. Set to
    * `Some(true)` when the caller (e.g. the Anthropic
    * `tool_result.is_error === true` translator) wants the model to
-   * treat the tool output as an error. The renderer prepends a short
-   * `[tool error]` prefix to `content` when emitting the wire-format
-   * tool response so the model receives a clear text-level cue, but
-   * the original `content` stays byte-for-byte intact in the
-   * structured form — no JSON wrapping, no in-band marker that could
-   * collide with a successful tool result whose literal content
-   * happens to start with the same prefix.
-   *
-   * `None` / `Some(false)` produce the unmarked wire format.
+   * treat the tool output as an error. It is exposed to the model's
+   * chat template as `message.is_error`; Rust never rewrites `content`
+   * or invents a model-facing error marker.
    */
   isError?: boolean;
   /** Reasoning content for thinking mode (used with <think> tags) */
@@ -2554,11 +2296,25 @@ export interface ChatResult {
   text: string;
   toolCalls: Array<ToolCallResult>;
   thinking?: string;
+  /**
+   * Effective `enable_thinking` boolean passed to the model-provided
+   * chat template for this turn. This is replay provenance and is
+   * intentionally distinct from the family's decode-time
+   * [`ThinkingSetup`](crate::engine::ThinkingSetup).
+   */
+  thinkingEnabled: boolean;
   numTokens: number;
   promptTokens: number;
   reasoningTokens: number;
   finishReason: string;
   rawText: string;
+  /**
+   * Reasoning-redacted raw output computed from the same token-aware
+   * boundary as `raw_text`. Session wrappers may request full reasoning
+   * internally for deterministic replay, then expose this safe view to a
+   * caller that set `includeReasoning: false`.
+   */
+  publicRawText?: string | undefined;
   /**
    * Number of prompt tokens served from the reused KV-cache prefix.
    *
@@ -2574,15 +2330,11 @@ export interface ChatResult {
   performance?: PerformanceMetrics;
 }
 
-/** Chat message role (lowercase values matching standard convention) */
+/** Chat message role (lowercase values matching standard convention). */
 export declare const enum ChatRole {
-  /** User message */
   User = 'user',
-  /** Assistant response */
   Assistant = 'assistant',
-  /** System prompt */
   System = 'system',
-  /** Tool response */
   Tool = 'tool',
 }
 
@@ -2593,10 +2345,23 @@ export interface ChatStreamChunk {
   finishReason?: string;
   toolCalls?: Array<ToolCallResult>;
   thinking?: string;
+  /**
+   * Effective template `enable_thinking` value. Present on the terminal
+   * chunk only; incremental text/reasoning chunks leave it unset.
+   */
+  thinkingEnabled?: boolean | undefined;
   numTokens?: number;
   promptTokens?: number;
   reasoningTokens?: number;
   rawText?: string;
+  /** Reasoning-redacted counterpart to `raw_text` on terminal chunks. */
+  publicRawText?: string | undefined;
+  /**
+   * Whether terminal `text` is the authoritative parsed assistant content.
+   * Generic emitters set true; Gemma streams visible content exclusively as
+   * deltas and set false so session history commits the accumulated text.
+   */
+  textAuthoritative?: boolean | undefined;
   /**
    * Number of prompt tokens served from the reused KV-cache prefix on
    * this turn. Populated on the terminal chunk (`done == true`) only;
@@ -2644,6 +2409,171 @@ export interface CleanupStats {
   logsDeleted: number;
 }
 
+/**
+ * Flush every accepted cold-tier block to disk, blocking until the
+ * background writer has fsync+renamed each write enqueued before this call,
+ * or `timeout_ms` elapses. Returns `true` when the drain completed — or when
+ * the tier was never opened (nothing to flush) — and `false` on timeout.
+ *
+ * Called from the agent's one-shot (`mlx agent -p`) shutdown so a prompt's
+ * just-persisted prefix blocks reach the drive before the process exits,
+ * rather than being abandoned in the write queue.
+ *
+ * The payload flush is `fsync(2)`, not `F_FULLFSYNC`: a drained block
+ * survives process death and kernel panic, but a sudden power loss can leave
+ * it torn. Torn objects fail the payload checksum on the next read and are
+ * pruned as a miss, so the cost is a recomputed prefix, never wrong state.
+ */
+export declare function coldCacheDrain(timeoutMs: number): boolean;
+
+/**
+ * Return a snapshot of the process-wide cold tier. Read-only: never opens
+ * the tier itself, so it reports `enabled: false` until inference first
+ * initializes the tier.
+ *
+ * The source snapshot is DESTRUCTURED rather than field-accessed, so a
+ * counter added to `ColdCacheStats` and forgotten here fails to compile.
+ * The failure this guards is silent and has already happened twice: a native
+ * counter that never reaches this struct reaches no JS consumer either, and
+ * nothing downstream can tell "the counter is zero" from "the counter was
+ * never carried across".
+ */
+export declare function coldCacheStats(): ColdCacheStats;
+
+/**
+ * Snapshot of the process-wide SSD cold tier for paged prefix blocks.
+ * Counters are cumulative since the tier was opened; all numeric values
+ * are returned as `f64` to avoid BigInt round-trips in JS.
+ */
+export interface ColdCacheStats {
+  /**
+   * `false` until the tier is first opened by inference, or when opening
+   * failed (fail-open: inference then runs without persistence).
+   */
+  enabled: boolean;
+  /** Cache root directory (empty while disabled). */
+  root: string;
+  /** Disk quota in bytes. */
+  quotaBytes: number;
+  /** Blocks restored from disk after validation. */
+  hits: number;
+  /** Lookups that found no usable block (includes corrupt entries). */
+  misses: number;
+  /**
+   * Objects accepted onto the background write queue — K/V blocks and
+   * family state sidecars alike, since both take a slot in the same queue.
+   * `coldSidecarEnqueued` counts a subset of this; never sum them.
+   */
+  enqueued: number;
+  /**
+   * Writes REFUSED at admission because the bounded queue was full. Same
+   * object scope as `enqueued`. Disjoint from `writeErrors`, which counts
+   * accepted writes that then failed to land — never sum the two into one
+   * "lost writes" number.
+   */
+  queueDrops: number;
+  /**
+   * Bytes that LANDED, credited after the payload sync, the commit rename
+   * and the directory fsync all succeeded. Not an enqueue-time estimate:
+   * a failed write credits nothing here and one `writeErrors` instead.
+   */
+  bytesWritten: number;
+  /** Total bytes read back on validated hits. */
+  bytesRestored: number;
+  /** Entries evicted to respect the quota / free-space reserve. */
+  evictions: number;
+  /** Entries that failed checksum/identity validation and were removed. */
+  corruptions: number;
+  /**
+   * Writes the queue accepted that never reached disk — a read-only, full
+   * or unmounted cache root, a failed rename, a failed fsync. The writer is
+   * fail-open and reports the error to nobody, so without this a cache that
+   * stores nothing at all still looks perfectly healthy.
+   */
+  writeErrors: number;
+  /**
+   * Restores refused before any block was looked up. Neither a hit nor a
+   * miss — so a refused restore reads as `0/0`, exactly like a turn that
+   * never consulted the tier.
+   */
+  restoreDeclines: number;
+}
+
+/**
+ * The native cold-restore allowlist, exposed so a test can assert it agrees
+ * exactly with the TypeScript `COLD_TIER_RESTORE_FAMILIES` set.
+ */
+export declare function coldRestoreFamilies(): Array<string>;
+
+/**
+ * Return the process-wide sidecar counters. Unlike [`cold_cache_stats`] this
+ * never consults the tier at all, so it is valid before any inference has run
+ * and reports honestly even when the tier failed to open.
+ *
+ * The plain-Rust [`cold_sidecar_telemetry`] stays as it is: the parity harness
+ * and the in-crate tests destructure `ColdSidecarTelemetry`, and a napi
+ * `#[napi(object)]` return type cannot serve both.
+ */
+export declare function coldSidecarStats(): ColdSidecarStats;
+
+/**
+ * Snapshot of [`ColdSidecarTelemetry`] for JS. Counters are cumulative since
+ * process start; all values are `f64` to avoid BigInt round-trips.
+ *
+ * Separate from [`ColdCacheStatsJs`] because this one isolates SIDECARS — the
+ * recurrent and sliding-window state that lives outside the pool — while that
+ * one is scoped to the write queue as a whole. Both structs carry an
+ * `enqueued` and a `queue_drops`, and they are NOT disjoint: a sidecar
+ * admission bumps both, so these are a subset of those and summing them
+ * double-counts. The JS side keeps them apart by prefix (`coldEnqueued` vs
+ * `coldSidecarEnqueued`); read the sidecar pair when you need "did the family
+ * state persist?", the block pair when you need "is the writer keeping up?".
+ */
+export interface ColdSidecarStats {
+  /**
+   * Turns that reached a family's sidecar capture at all. Every other
+   * counter here is a sub-count of this one, so `captureReached == 0`
+   * separates "the finalize path never calls the capture" from "the capture
+   * ran and declined".
+   */
+  captureReached: number;
+  /**
+   * Turns whose persisted K/V chain covered no whole block, so there was no
+   * prefix to anchor recurrent state under.
+   */
+  chainEmpty: number;
+  /**
+   * Turns whose chain covered blocks but where no retained checkpoint sat at
+   * or below its reach.
+   */
+  boundarySkips: number;
+  /**
+   * Turns that selected a boundary already on disk — nothing written, and
+   * nothing needed to be. The steady state of a repeated prompt, and the
+   * only thing that tells a healthy run from a collapsed ladder.
+   */
+  alreadyPersisted: number;
+  /** Sidecars handed to the bounded writer queue. */
+  enqueued: number;
+  /** Sidecars the bounded writer queue refused because it was full. */
+  queueDrops: number;
+  /**
+   * Restored sidecars a family actually INSTALLED as its live per-turn
+   * state. The one read-side counter, and the only signal that separates
+   * "restored and used" from "restored and silently re-derived by a full
+   * O(prefix) replay" — every other counter, and text parity itself, is
+   * satisfied by the replay.
+   */
+  installed: number;
+  /**
+   * Restores a family THREW AWAY after the walk served them, restarting the
+   * turn cold. Unlike `ColdCacheStats.restoreDeclines` this one comes AFTER
+   * real `coldHits` and `coldBytesRestored`, so the turn looks like it
+   * reused a prefix right up to the point where it recomputed all of it.
+   */
+  restoreSuppressed: number;
+}
+
 /**
  * Structured completion information aligned with ChatResult.
  * Contains pre-parsed tool calls, thinking, and clean text.
@@ -2945,6 +2875,26 @@ export interface FunctionParameters {
   required?: Array<string>;
 }
 
+/**
+ * How many GDN prefix checkpoints the native store holds across all owners
+ * ([`GDN_PREFIX_CHECKPOINT_LIMIT`]), exposed for the same reason
+ * [`cold_restore_families`] is: it is one half of a cross-language invariant
+ * and nothing else carries it over the boundary.
+ *
+ * The other half is `MAX_CONCURRENCY` in
+ * `packages/agent/src/extensions/subagent.ts`. The store's demand is
+ * `MAX_CONCURRENCY + 1` — one owner per concurrent child loop plus the root
+ * session — and the cliff sits exactly one owner past the cap, where every
+ * owner holds a single entry and the store is still over it, so each publish
+ * takes somebody's last checkpoint. `retention_sim` measures that as 0 blind
+ * turns at five owners and 28 of 40 at six.
+ *
+ * No Rust gate can see a TypeScript-only edit, so raising the fleet alone
+ * would land in that regime with every Rust gate still green.
+ * `packages/agent/__test__/gdn-checkpoint-capacity.test.ts` is what stops it.
+ */
+export declare function gdnPrefixCheckpointLimit(): number;
+
 /**
  * Gemma 4 model configuration (dense variant).
  *
@@ -3078,6 +3028,15 @@ export interface Gemma4Config {
    * real Gemma-4-E2B weights.
    */
   useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist full paged KV blocks — and gemma4's out-of-pool sliding-window
+   * state, as a cold-tier sidecar — to the SSD cold tier so warm prefixes
+   * survive process restarts. Off unless explicitly enabled.
+   *
+   * An EXPLICIT value here is authoritative and beats the ambient
+   * `MLX_PERSIST_PAGED_CACHE` default (`cold_tier::resolve_persist_cold`).
+   */
+  persistPagedCache?: boolean | undefined;
 }
 
 /** Optional load-time settings for [`Gemma4Model::load`]. */
@@ -3321,6 +3280,14 @@ export interface GgufConversionOptions {
    * Forces `group_size = 32` for upgraded layers.
    */
   quantMxfp?: boolean;
+  /**
+   * Import ggml Q4_K / Q5_K / Q6_K tensors as MLX K-quant arrays instead of
+   * rejecting them (default: false). The blocks are repacked, never
+   * dequantized, so the output keeps the source file's weights and byte size.
+   * With this off, Q6_K remains the Gemma4 token-embedding BF16 fallback and
+   * Q4_K / Q5_K are an error.
+   */
+  importKQuants?: boolean;
 }
 
 export interface GgufConversionResult {
@@ -3733,6 +3700,21 @@ export interface ModelConfig {
   eosTokenId: number;
 }
 
+/**
+ * Ordering policy for structured multimodal content parts handed to a
+ * checkpoint-provided Jinja template.
+ *
+ * The default preserves the generic serializer's existing text-before-media
+ * behavior. PaddleOCR-VL and Qianfan-OCR were trained with image placeholders
+ * before the instruction and opt into
+ * [`MultimodalContentOrder::ImagesThenText`] at their adapter boundaries.
+ * Audio remains after text in both modes.
+ */
+export declare const enum MultimodalContentOrder {
+  TextThenMedia = 'textThenMedia',
+  ImagesThenText = 'imagesThenText',
+}
+
 /** Result from document orientation classification. */
 export interface OrientationResult {
   /** Detected rotation angle (0, 90, 180, or 270 degrees) */
@@ -4120,6 +4102,13 @@ export interface Qwen35Config {
    * `Some(true)` for VLM checkpoints (block-paged, set in `parse_config`).
    */
   useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist the out-of-pool GDN recurrent state (and the paged KV blocks it
+   * gates) to the SSD cold tier so warm prefixes survive process restarts.
+   * Off unless explicitly enabled. See `crate::models::qwen3_5::gdn_sidecar`
+   * and `crate::cold_tier::resolve_persist_cold`.
+   */
+  persistPagedCache?: boolean | undefined;
   /**
    * Number of MTP (Multi-Token Prediction) head layers shipped with the
    * checkpoint. Populated from `mtp_num_hidden_layers` /
@@ -4227,6 +4216,14 @@ export interface Qwen35MoeConfig {
    * Default: `None` / `false`.
    */
   useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist the out-of-pool GDN recurrent state (and the paged KV blocks it
+   * gates) to the SSD cold tier so warm prefixes survive process restarts.
+   * Off unless explicitly enabled. Shares the dense qwen3_5 GDN sidecar codec
+   * (`crate::models::qwen3_5::gdn_sidecar`) via `to_dense_config`; the
+   * precedence rules live in `crate::cold_tier::resolve_persist_cold`.
+   */
+  persistPagedCache?: boolean | undefined;
   /**
    * Number of MTP (Multi-Token Prediction) head layers shipped with
    * the checkpoint. Populated from `mtp_num_hidden_layers` /
@@ -4294,6 +4291,11 @@ export interface Qwen3Config {
    * Default: true.
    */
   useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist full paged KV blocks to the SSD cold tier so warm prefixes
+   * survive process restarts. Off unless explicitly enabled.
+   */
+  persistPagedCache?: boolean | undefined;
 }
 
 /** Qwen3 language model configuration */
@@ -4750,51 +4752,32 @@ export interface VisionConfig {
   spatialMergeSize: number;
 }
 
-/** A batch item for VLM batch inference */
 export interface VlmBatchItem {
-  /** Chat messages for this item */
   messages: Array<VlmChatMessage>;
-  /** Encoded image buffers for this item (one image per item for OCR) */
   images?: Array<Buffer>;
 }
 
-/** Configuration for VLM chat */
 export interface VlmChatConfig {
-  /** Encoded image buffers to process (PNG/JPEG bytes) */
   images?: Array<Buffer>;
-  /** Maximum number of new tokens to generate (default: 512) */
   maxNewTokens?: number;
-  /** Sampling temperature (0 = greedy, higher = more random) (default: 0.0 for OCR) */
   temperature?: number;
-  /** Top-k sampling (default: 0) */
   topK?: number;
-  /** Top-p (nucleus) sampling (default: 1.0) */
   topP?: number;
-  /** Repetition penalty (default: 1.5) */
   repetitionPenalty?: number;
-  /**
-   * Presence penalty (0.0 = disabled). Subtracts a flat penalty from logits of any
-   * token that appeared at least once in context. Matches OpenAI API semantics.
-   */
   presencePenalty?: number;
-  /** Number of recent tokens to consider for presence penalty (default: 20) */
   presenceContextSize?: number;
-  /**
-   * Frequency penalty (0.0 = disabled). Subtracts penalty * occurrence_count from
-   * logits of each token in context. Matches OpenAI API semantics.
-   */
   frequencyPenalty?: number;
-  /** Number of recent tokens to consider for frequency penalty (default: 20) */
   frequencyContextSize?: number;
-  /** Whether to return log probabilities (default: false) */
   returnLogprobs?: boolean;
 }
 
-/** A chat message with optional image */
+/**
+ * A chat message with textual content. Images are supplied through
+ * [`VLMChatConfig`] and attached to the first user content part before the
+ * model template is rendered.
+ */
 export interface VlmChatMessage {
-  /** Role of the message sender */
   role: ChatRole;
-  /** Text content of the message */
   content: string;
 }