@mlx-node/lm 0.0.6 → 0.0.8

package/dist/chat-session.d.ts

@@ -0,0 +1,700 @@
+import type { ChatConfig, ChatMessage, ChatResult, ToolDefinition } from '@mlx-node/core';
+import type { ChatStreamEvent } from './stream.js';
+/**
+ * Stable, provider-neutral error raised before native inference when a
+ * rendered prompt cannot fit in the model's physically available hot KV
+ * window. The marker is intentionally the canonical string recognized by
+ * pi's overflow recovery, so managed agent sessions compact and retry while
+ * stateless HTTP callers receive a clean request error instead of a native
+ * `BlockAllocator exhausted` failure.
+ */
+export declare class ContextCapacityError extends Error {
+    readonly promptTokens: number;
+    readonly effectiveWindowTokens: number;
+    readonly code = "context_length_exceeded";
+    constructor(promptTokens: number, effectiveWindowTokens: number);
+}
+/** Recognize both the typed JS preflight and the native hard backstop. */
+export declare function isContextCapacityError(error: unknown): boolean;
+/** Physical and trained context limits captured by a native model at load. */
+export interface SessionContextLimits {
+    trainedWindowTokens: number;
+    effectiveWindowTokens: number;
+    pagedBlockCapacity: number;
+    pagedBlockSize: number;
+}
+/**
+ * Structural interface matched by every generative model wrapper
+ * (`Qwen35Model`, `Qwen35MoeModel`, `Lfm2Model`, `Gemma4Model`,
+ * `Qwen3Model`, and the Qianfan-OCR VLM wrapper). `ChatSession<M>` is
+ * generic over `M extends SessionCapableModel` so each session
+ * instance statically binds to a specific model's concrete type
+ * (handy for IDE autocomplete) while the implementation remains
+ * fully structural.
+ */
+export interface SessionCapableModel {
+    /**
+     * Optional non-generating chat-template tokenizer. Exposed by
+     * wrappers that can count prompt tokens without running inference
+     * (used by Anthropic `/v1/messages/count_tokens`).
+     */
+    applyChatTemplate?(messages: ChatMessage[], addGenerationPrompt?: boolean | null, tools?: ToolDefinition[] | null, enableThinking?: boolean | null): Promise<Uint32Array> | Uint32Array;
+    /**
+     * Optional model-native planner for prompt formats whose media placeholders
+     * expand after chat-template rendering. It returns the exact token length
+     * that inference will prefill, without mutating model/session state.
+     *
+     * Qwen3.5 dense/MoE implement this with their loaded image processor. Models
+     * without post-template expansion omit it and retain raw template counting.
+     */
+    expandedPromptTokenCount?(promptTokens: Uint32Array, messages: ChatMessage[]): Promise<number> | number;
+    /**
+     * Optional synchronous load-time snapshot of the model's usable context.
+     * Qwen3.5 dense/MoE expose this when adaptive paged-cache sizing is active.
+     */
+    contextLimits?(): SessionContextLimits;
+    /**
+     * Whether this loaded model instance has a complete image-input path.
+     *
+     * Optional so text-only and older wrappers continue to satisfy the
+     * structural contract. Supporting native wrappers snapshot this value after
+     * load, once the vision encoder/processor and any required cache backend are
+     * known to be available.
+     */
+    supportsImages?(): boolean;
+    chatSessionStart(messages: ChatMessage[], config?: ChatConfig | null): Promise<ChatResult>;
+    chatSessionContinue(userMessage: string, images: Uint8Array[] | null, audio: Uint8Array[] | null, config?: ChatConfig | null): Promise<ChatResult>;
+    chatSessionContinueTool(toolCallId: string, content: string, config?: ChatConfig | null, isError?: boolean | null): Promise<ChatResult>;
+    /**
+     * The optional `signal` parameter on every streaming entry point is
+     * plumbed into the `_runChatStream` fast-abort path in the wrapper
+     * implementations. Callers that need client-disconnect-aware
+     * cancellation (e.g. HTTP endpoints flipping an AbortController on
+     * socket close) can attach one here and the native decode unwinds
+     * at the next safepoint via `ChatStreamHandle.cancel()`. Non-signal
+     * callers (the common direct-use path) just omit it.
+     */
+    chatStreamSessionStart(messages: ChatMessage[], config?: ChatConfig | null, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
+    chatStreamSessionContinue(userMessage: string, images: Uint8Array[] | null, audio: Uint8Array[] | null, config?: ChatConfig | null, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
+    chatStreamSessionContinueTool(toolCallId: string, content: string, config?: ChatConfig | null, signal?: AbortSignal, isError?: boolean | null): AsyncGenerator<ChatStreamEvent>;
+    resetCaches(): void;
+    /**
+     * Whether the underlying native model has the block-paged KV cache
+     * adapter (`PagedKVCacheAdapter` + `BlockAllocator` + `LayerKVPool`)
+     * active.
+     *
+     * `true` iff the adapter was successfully constructed at load time
+     * (driven by the per-model `use_block_paged_cache` config flag, which
+     * defaults to ON for Qwen3 + LFM2 after parity verification and OFF
+     * for Gemma4 + Qwen3.5 + Qwen3.5 MoE pending parity validation; also
+     * always `false` on Qwen3.5 VLM checkpoints where
+     * `set_vision_encoder` rejects when the adapter is populated).
+     *
+     * When `true`, the native cache reuses SYS blocks across requests via
+     * content-addressing in the `BlockAllocator`'s prefix-hash table —
+     * the JS-side warm slot in
+     * `SessionRegistry.getOrCreateWarmAny(requestedSystem)` becomes
+     * redundant for stateless `/v1/messages` traffic. The server
+     * endpoint reads this getter to decide whether to allocate a fresh
+     * `ChatSession` per request (paged-active) or to lease the warm slot
+     * (non-paged); see `packages/server/src/endpoints/messages.ts`.
+     *
+     * Optional on the structural interface so models that pre-date the
+     * NAPI getter (notably `QianfanOCRModel` from `@mlx-node/vlm`, which
+     * has no paged-adapter wiring) still satisfy the type contract — a
+     * missing getter is treated as `false` (not paged) by callers.
+     * Surfaced as a synchronous method on every native wrapper that DOES
+     * support paged so the routing decision in the server doesn't need a
+     * model-thread roundtrip per request — the value is captured at load
+     * time and never changes for a given model instance.
+     */
+    hasBlockPagedCache?(): boolean;
+    /**
+     * MTP: whether the underlying native model can run speculative
+     * decoding. Surfaced by `Qwen3_5Model` / `Qwen3_5MoeModel` (an MTP
+     * head shipped in the checkpoint and loaded by persistence) and by
+     * `Gemma4Model` (an external draft model — DSpark or Google gemma-4
+     * assistant, auto-detected from the draft's config.json — attached
+     * via `loadModel` / `loadSession` `draftModelPath`; NOT in-checkpoint
+     * MTP heads); all other native wrappers omit the method, in
+     * which case callers treat a missing getter as `false` (no MTP).
+     *
+     * When `true`, {@link ChatSession#mergeConfig} auto-defaults the
+     * per-request `enableMtp` flag to `true` — the speculative-decode
+     * path takes over unless the caller explicitly opts out by passing
+     * `enableMtp: false` in their `ChatConfig` overlay. When `false`
+     * (or the method is missing), `enableMtp` is left untouched.
+     *
+     * Synchronous on every supporting wrapper so the auto-default check
+     * doesn't need a model-thread roundtrip per call — the value is
+     * captured at load time and never changes for a given model
+     * instance.
+     *
+     * ## Companion `ChatConfig` knobs (only meaningful when `enableMtp` is on)
+     *
+     * Two related `ChatConfig` fields tune the speculative-decode loop.
+     * They are forwarded verbatim to the native side via
+     * {@link SendOptions.config} (per-call overlay) or
+     * {@link ChatSessionOptions.defaultConfig} (session default), and
+     * `mergeConfig` shallow-merges per-call over per-session so an
+     * explicit per-send value always wins over the session default for
+     * the same field.
+     *
+     * - **`mtpDepth`** — pins the MTP draft depth per speculative cycle.
+     *   On Qwen3.5 native MTP heads it is clamped to `[1, 5]` by the
+     *   verify FFI contract, and when unset native code currently pins
+     *   depth 1. Setting `mtpDepth` explicitly pins that value unless
+     *   the caller also passes `mtpAdaptiveDepth: true` to opt into
+     *   adaptive depth with the supplied maximum/seed. Gemma4 external
+     *   drafts resolve the field per draft variant instead — see the
+     *   Gemma4 section below.
+     * - **`mtpAdaptiveDepth`** — toggles the adaptive depth policy.
+     *   Defaults to OFF for native MTP and assistants (Gemma4 DSpark has the
+     *   family override documented below). When ON, the native-MTP default
+     *   mode runs a 5-state machine
+     *   (`Explore` → `Full` → {`NeighborProbe` | `Reduced` → `Probe`})
+     *   with per-depth EMA tracking of
+     *   `accepted_tokens / cycle_wall_ns` and picks the depth that
+     *   maximizes that rate (DFlash-style, EMA decay α=0.3, drop-back
+     *   threshold 0.75). `MLX_MTP_ADAPTIVE_DEPTH_MODE=expected-value`
+     *   instead uses the MTPLX-style intra-cycle expected-value gate; by
+     *   default it stops at its base depth, with deeper expansion kept
+     *   research-only behind `MLX_MTP_EV_ALLOW_DEEPEN=1`.
+     *   An explicit `false` always wins, pinning the chosen `mtpDepth` for
+     *   every cycle. When `enableMtp` is false (or the model has no MTP
+     *   head) the field is ignored.
+     *
+     * The defaults for both `mtpDepth` and `mtpAdaptiveDepth` are
+     * applied on the native side (see
+     * `crates/mlx-core/src/models/qwen3_5/chat_common.rs` MTP runtime
+     * flag inventory), so omitting them from `defaultConfig` /
+     * `SendOptions.config` is the recommended path for callers that
+     * just want speculative decoding "on with sensible defaults".
+     *
+     * ## Gemma4 external drafts (`draftModelPath`)
+     *
+     * Gemma4 reinterprets the knobs per draft variant (resolved in
+     * `gemma4/model.rs` `resolve_params`, always from the RAW config
+     * value — the engine's central `[1, 5]` clamp is an MTP-head
+     * contract that does not apply to external drafts):
+     *
+     * - **DSpark**: with both knobs unset, full draft blocks (the
+     *   checkpoint's block size — 7 tokens on
+     *   `dspark_gemma4_12b_block7`) run behind a short per-turn measurement
+     *   against target-only AR. If DSpark loses on the current host/context,
+     *   that turn permanently falls back to exact target-only decoding. An
+     *   insufficiently long generation budget preserves the fixed-block path.
+     *   An explicit `mtpDepth` acts as a CAP on the block (clamped to
+     *   `[1, blockSize]`) and pins it unless `mtpAdaptiveDepth: true` opts the
+     *   guard back in. Explicit `mtpAdaptiveDepth: false` disables the guard.
+     * - **Assistant** (Google `gemma-4-*-it-assistant`): chained AR
+     *   drafting has no checkpoint-pinned block size — an unset
+     *   `mtpDepth` drafts 3 tokens per cycle (`ASSISTANT_DEFAULT_DEPTH`,
+     *   a quality/latency tradeoff, not a checkpoint contract), and an
+     *   explicit `mtpDepth` clamps to `[1, 8]` (`ASSISTANT_MAX_DEPTH`).
+     *
+     * `mtpAdaptiveDepth` remains ignored for the assistant variant. Qwen3.5
+     * native-MTP semantics above are unchanged.
+     */
+    hasMtpWeights?(): boolean;
+}
+/** Per-call options for {@link ChatSession#send} / `sendStream`. */
+export interface SendOptions {
+    /**
+     * Optional image bytes attached to this user turn. When the image
+     * set differs from the session's current `lastImagesKey`, the
+     * session forcibly restarts via `chatSessionStart`.
+     */
+    images?: Uint8Array[];
+    /**
+     * Optional audio bytes (encoded WAV) attached to this user turn. When
+     * the audio set differs from the session's current `lastAudioKey`, the
+     * session forcibly restarts via `chatSessionStart` (mirrors `images`).
+     * Only the unified Gemma 4 audio checkpoint consumes this.
+     */
+    audio?: Uint8Array[];
+    /**
+     * Per-call `ChatConfig` overlay applied on top of the session's
+     * `defaultConfig`. `reuseCache` is always forced on regardless of
+     * what the caller passes. The overlay is shallow-merged on top of
+     * the session default, so per-call values always win over per-session
+     * values for the same field — including the speculative-decode
+     * knobs `enableMtp`, `mtpDepth`, and `mtpAdaptiveDepth`. See
+     * {@link SessionCapableModel.hasMtpWeights} for the full MTP knob
+     * surface and default-resolution rules.
+     */
+    config?: ChatConfig;
+    /**
+     * Optional AbortSignal plumbed into the streaming fast-abort path.
+     *
+     * Only honored by the streaming entry points (`sendStream`,
+     * `sendToolResultStream`, `startFromHistoryStream`) — the
+     * non-streaming `send` / `sendToolResult` / `startFromHistory`
+     * calls have NO native cancel surface, so a signal passed to them
+     * is ignored. Pass one here and the inner `_runChatStream`
+     * adapter wakes from `waitForItem()` on abort, calls
+     * `handle.cancel()` on the native handle, and unwinds the stream
+     * without throwing an AbortError — the outer consumer's `for await`
+     * just ends early. Intended for HTTP endpoints that flip a
+     * controller on `res.once('close', …)` so client disconnect stops
+     * the native decode at the next safepoint rather than running it
+     * to completion under the per-model mutex.
+     */
+    signal?: AbortSignal;
+}
+/** Constructor options for {@link ChatSession}. */
+export interface ChatSessionOptions {
+    /**
+     * Optional system prompt prepended as the first message on turn 1.
+     * Subsequent turns don't re-inject the system prompt — the cache
+     * already holds it.
+     */
+    system?: string;
+    /**
+     * Default `ChatConfig` applied to every `send()` / `sendStream()`
+     * / `sendToolResult()` call. Per-call config is shallow-merged on
+     * top of this, and `reuseCache` is forced on. Speculative-decode
+     * knobs (`enableMtp`, `mtpDepth`, `mtpAdaptiveDepth`) can be parked
+     * here as session-wide defaults and overridden per call via
+     * {@link SendOptions.config}; see
+     * {@link SessionCapableModel.hasMtpWeights} for the MTP knob surface
+     * and default-resolution rules.
+     */
+    defaultConfig?: ChatConfig;
+}
+/**
+ * Cross-model chat session. See module docstring for design notes.
+ *
+ * The generic parameter `M` statically captures the concrete model
+ * type so the structural interface stays as expressive as the
+ * concrete one. Internally the class only uses the
+ * `SessionCapableModel` surface.
+ */
+export declare class ChatSession<M extends SessionCapableModel = SessionCapableModel> {
+    private readonly model;
+    private readonly system;
+    private readonly defaultConfig;
+    /**
+     * Full conversation history tracked on the TS side. Appended to on
+     * every successful turn. Only read back when the image-change path
+     * triggers a restart — normal text continues use the server-side
+     * cache, not this array.
+     */
+    private history;
+    /**
+     * Hex-encoded byte-identity key of the image set currently bound
+     * to the server's KV cache (SHA-256; see `computeImagesKey`).
+     * `null` when no images are cached. A `send()` whose new key
+     * differs triggers a full `chatSessionStart` restart.
+     */
+    private lastImagesKey;
+    /**
+     * Hex-encoded byte-identity key of the audio set currently bound to the
+     * server's KV cache (see {@link computeAudioKey}). `null` when no audio is
+     * cached. A `send()` whose new key differs triggers a full
+     * `chatSessionStart` restart — the audio counterpart of `lastImagesKey`.
+     */
+    private lastAudioKey;
+    private turnCount;
+    private inFlight;
+    /** A failed/abandoned native delta must be followed by a full replay. */
+    private needsFullReplay;
+    /**
+     * Count of `ok` tool calls emitted by the prior assistant turn, or
+     * `null` when the prior turn produced none. Gates every continuation
+     * entry point on the tool-call resolution invariant because each
+     * native `chat_session_continue*` dispatch re-opens the assistant
+     * turn:
+     *
+     *   - A plain text `send` / `sendStream` after ANY outstanding tool
+     *     call would orphan the call(s) by weaving a fresh user turn
+     *     between the assistant's `tool_call` and any response.
+     *   - A `sendToolResult` / `sendToolResultStream` is only servable
+     *     when exactly one tool call is outstanding. A multi-call
+     *     fan-out (`> 1`) cannot be resolved one result at a time — the
+     *     siblings would be separated by fresh assistant replies — so
+     *     those entry points also reject.
+     *
+     * Cleared on every successful commit whose new turn emits zero `ok`
+     * tool calls, and on `reset()`. See `assertCanSendPlain` /
+     * `assertCanSendToolResult` for the per-entry-point gate logic.
+     */
+    private unresolvedOkToolCallCount;
+    constructor(model: M, options?: ChatSessionOptions);
+    /**
+     * Number of completed turns. Increments only after a successful
+     * round-trip — in-flight or failed calls leave this untouched.
+     */
+    get turns(): number;
+    /** Whether the session currently has images bound to its cache. */
+    get hasImages(): boolean;
+    /** Load-time physical context snapshot, when exposed by the model. */
+    contextLimits(): SessionContextLimits | undefined;
+    /** Authoritative image-input capability of the loaded native model. */
+    supportsImages(): boolean;
+    /**
+     * Render and validate a complete message list against the model's physical
+     * context window without starting inference or mutating session/native cache
+     * state.
+     *
+     * HTTP streaming callers use this before committing SSE headers so an
+     * oversized prompt can still receive a protocol-shaped 400 response without
+     * delaying those headers until image processing, prefill, or the first
+     * generated token. The returned config carries the same output-budget clamp
+     * applied by the send entry points; those entry points intentionally repeat
+     * the check against their own authoritative history before native dispatch.
+     */
+    preflightContextCapacity(messages: readonly ChatMessage[], config?: ChatConfig): Promise<ChatConfig>;
+    /**
+     * Capacity-preflight one pending user/tool message against this session's
+     * preserved history without starting inference or mutating cache state.
+     *
+     * This is the exact counterpart of the delta `send*` paths. It matters for
+     * server-side prompt-cache hits where the HTTP request contains only the new
+     * message while the leased ChatSession owns the earlier conversation.
+     */
+    preflightPendingContextCapacity(pending: ChatMessage, config?: ChatConfig): Promise<ChatConfig>;
+    /**
+     * Count of `ok` tool calls from the most recent assistant turn, or
+     * `null` when the trailing turn produced none. Non-null means the
+     * session is parked on an unresolved tool-call turn and the only
+     * forward-progress move is `sendToolResult*()` against one of the
+     * outstanding ids — and only when the count is exactly 1. A
+     * multi-call fan-out (`> 1`) cannot be served by the chat-session
+     * API at all; server endpoints should pre-check this getter and
+     * route around a fan-out via `reset()` + `primeHistory()` +
+     * `startFromHistory()` cold replay that resolves every sibling in
+     * one atomic jinja render.
+     *
+     * The flag updates after every successful `send` / `sendStream` /
+     * `sendToolResult` / `sendToolResultStream` / `startFromHistory*`
+     * commit, and after `primeHistory()` (from the trailing assistant
+     * message's `toolCalls.length`). `reset()` clears it.
+     */
+    get pendingUnresolvedToolCallCount(): number | null;
+    /**
+     * Send a user message and resolve with the assistant reply.
+     *
+     * Turn 0 and any turn whose image set has changed dispatch through
+     * `chatSessionStart` with the full history. All other turns use
+     * the cheap `chatSessionContinue` delta path.
+     */
+    send(userMessage: string, opts?: SendOptions): Promise<ChatResult>;
+    /**
+     * Streaming variant of {@link ChatSession#send}.
+     *
+     * Routing matches `send()`. The assistant reply is accumulated
+     * from stream deltas and pushed to `history` only after a
+     * successful terminal chunk (`done: true` with non-error
+     * `finishReason`). Caller break, mid-stream exceptions, and error
+     * finishes all leave `turnCount` untouched and the history
+     * un-appended for the turn so the next call re-routes through the
+     * start path.
+     */
+    sendStream(userMessage: string, opts?: SendOptions): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * Send a tool-result turn. Always dispatches
+     * `chatSessionContinueTool` — tool turns never change image state,
+     * so there is no restart path here.
+     *
+     * Rejects if the prior assistant turn emitted more than one `ok`
+     * tool call: the chat-session API only supports exactly one tool
+     * call per assistant turn because each `sendToolResult` dispatch
+     * immediately re-opens the assistant turn, so responding to the
+     * remaining calls would interleave new assistant replies between
+     * the results and corrupt the conversation structure. Callers that
+     * hit this must tighten the prompt / tool spec or reset the
+     * session.
+     *
+     * `isError` is the structured tool-error signal. When `true`, the
+     * native renderer prepends a short, model-facing error marker to
+     * `content` inside the wire-format tool block so the model
+     * receives a clear text-level cue that the tool result represents
+     * a failure. The structured field is stored verbatim on the
+     * appended `{ role: 'tool', ... }` history entry so cold-replay
+     * (image-change restart, `startFromHistory*`, server-side
+     * `SessionRegistry` cache-miss rebuild) re-renders the marker
+     * consistently with the live turn. Defaults to `undefined` (no
+     * marker). Pass through verbatim — we do NOT infer error from
+     * `content`.
+     *
+     * Appends a `{ role: 'tool', ... }` message to history on success.
+     */
+    sendToolResult(toolCallId: string, content: string, opts?: {
+        isError?: boolean;
+        config?: ChatConfig;
+    }): Promise<ChatResult>;
+    /**
+     * Cold-replay a tool result through the start path: re-render the
+     * full preserved history (including the prior media turn and the
+     * unresolved tool-call assistant turn) plus this tool message. Used
+     * when the native session is cold (turnCount===0 — e.g. after an
+     * interrupted media-held replay rolled the cache back) and by the
+     * media-held rejection catch. `mediaChanged=true` forces a
+     * resetCaches so the prefill always starts from a guaranteed-clean
+     * cache; `isFirstTurn=false` because a tool result always follows a
+     * prior tool-call turn.
+     */
+    private replayToolResultThroughStartPath;
+    /**
+     * Streaming variant of {@link ChatSession#sendToolResult}.
+     *
+     * `isError` mirrors the non-streaming entry point — when `true`,
+     * the native renderer prepends a short, model-facing error marker
+     * to `content` inside the wire-format tool block. The structured
+     * field is stored verbatim on the appended `{ role: 'tool', ... }`
+     * history entry so cold-replay re-renders the marker consistently
+     * with the live streaming turn.
+     */
+    sendToolResultStream(toolCallId: string, content: string, opts?: {
+        isError?: boolean;
+        config?: ChatConfig;
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * Streaming counterpart of {@link replayToolResultThroughStartPath}:
+     * cold-replay a tool result through the start stream. Used by the
+     * turn-0 precheck and the media-held rejection catch in
+     * {@link sendToolResultStream}. The start stream owns the history
+     * push, turnCount increment, and media-key rehydration; callers keep
+     * `delegated`/early-return semantics so the commit `finally` stays
+     * off.
+     */
+    private replayToolResultThroughStartStreamPath;
+    /**
+     * Reset the session state.
+     *
+     * Clears the underlying model's KV caches and wipes local history,
+     * image key, and turn counter so the next `send()` goes through
+     * `chatSessionStart` again.
+     *
+     * This is a full wipe — safe default for public callers. It always
+     * calls `model.resetCaches()`, which is the ONLY behavior exposed
+     * on the public API because the underlying `SessionCapableModel`
+     * is shared across every `ChatSession` lifetime via the native
+     * `ModelRegistry`: a partial wipe that leaves the shared native
+     * KV cache intact would leak a previous (unrelated) request's
+     * cached prefix into the next `chat_session_start_sync` call. The
+     * server-side warm-lease replay path (where preserving the native
+     * cache is correct) uses its own server-private helper gated by
+     * the `SessionRegistry` HIT signal — the only authoritative proof
+     * that the native cache genuinely belongs to this chain. That
+     * helper lives inside `@mlx-node/server`, never touches the
+     * `@mlx-node/lm` export map, and is not reachable from downstream
+     * consumers. Public consumers of `@mlx-node/lm` have no such HIT
+     * signal, so the public API intentionally offers only the full-wipe
+     * option.
+     *
+     * Returns `Promise<void>` for an async-friendly signature even
+     * though `resetCaches()` is currently synchronous.
+     */
+    reset(): Promise<void>;
+    /**
+     * Prime the session history without running inference.
+     *
+     * Used by the server-side `SessionRegistry` cold-start fallback: when
+     * a request arrives with a `previous_response_id` that the cache has
+     * missed, the endpoint reconstructs the full conversation from the
+     * `ResponseStore` and primes a fresh session with it, then calls
+     * `startFromHistory()` to replay it through the native KV cache.
+     *
+     * Rejects if the session is in flight or has already taken a turn.
+     * Replaces the internal history with a shallow copy of `messages`.
+     */
+    primeHistory(messages: ChatMessage[]): void;
+    /**
+     * Run a cold-start `chatSessionStart` using the currently primed
+     * history.
+     *
+     * Intended pairing with {@link primeHistory}: call
+     * `primeHistory(fullHistory)` first, then `startFromHistory()` to
+     * replay the conversation through the native chat-session API. The
+     * final history entry must be a user or tool turn — this is what the
+     * native side treats as the "current input" to generate against.
+     *
+     * Pushes the assistant reply onto the history, advances `turnCount`
+     * to 1, and computes `lastImagesKey` from the most recent user
+     * message that carries images (so subsequent text-only continues
+     * stay on the delta path, and subsequent image turns correctly
+     * trigger restart).
+     */
+    startFromHistory(config?: ChatConfig): Promise<ChatResult>;
+    /**
+     * Streaming counterpart to {@link startFromHistory}.
+     *
+     * Iterates `model.chatStreamSessionStart(history.slice(), config)`,
+     * accumulates text, and only commits history + `turnCount` +
+     * `lastImagesKey` in the `finally` block when a successful terminal
+     * chunk was observed (`done: true` with non-error finishReason).
+     * Because history is primed (not appended to), rollback on failure
+     * is a no-op: the primed state stays intact so the caller can retry.
+     */
+    startFromHistoryStream(config?: ChatConfig, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * Gate plain-text continuation entry points (`send`, `sendStream`)
+     * on the tool-call resolution invariant. Any outstanding `ok` tool
+     * call from the prior assistant turn — single or multi — makes a
+     * plain text continuation unsafe: the native chat-session API
+     * re-opens the assistant turn on each continue, so a new user delta
+     * would weave a fresh user message between the assistant's
+     * `tool_call` and any response, orphaning the call. Callers must
+     * resolve outstanding calls via `sendToolResult*()` (single-call
+     * case) or re-enter via `reset()` + `primeHistory()` +
+     * `startFromHistory()` with a resolved conversation (multi-call
+     * fan-out). `reset()` clears the flag and `startFromHistory*`
+     * overwrites it via `recordToolCallFanout` on the new response, so
+     * legitimate recovery paths are unaffected.
+     */
+    private assertCanSendPlain;
+    /**
+     * Gate tool-result entry points (`sendToolResult`,
+     * `sendToolResultStream`) on the single-tool-call-per-turn
+     * invariant. Exactly one outstanding tool call is servable — that
+     * is the case these methods exist for.
+     *
+     * Zero outstanding calls (`null`) is also unservable: without a
+     * preceding assistant turn that emitted a tool call, a tool-result
+     * dispatch would synthesize a `<tool_response>` delta for a call
+     * that never existed, corrupting the conversation structure. The
+     * native backends do not authenticate `tool_call_id` against prior
+     * state — several simply append the tool-response delta verbatim —
+     * so rejecting here is the only gate that prevents forged tool
+     * state from reaching the model. Callers that want to start a
+     * conversation on a resolved tool turn must prime an unresolved
+     * single-call assistant turn via `primeHistory()` +
+     * `startFromHistory()` first.
+     *
+     * A multi-call fan-out (`> 1`) cannot be resolved one result at a
+     * time because each `sendToolResult` dispatch immediately re-opens
+     * the assistant turn, so responding to the siblings would
+     * interleave new assistant replies between the results.
+     */
+    private assertCanSendToolResult;
+    /**
+     * Inspect a just-committed turn's tool calls and store the count of
+     * `ok` entries in `unresolvedOkToolCallCount`. Any non-zero count
+     * parks the session on an unresolved tool-call turn, which gates
+     * the next entry point:
+     *
+     *   - count === 0 → flag is `null`: `send`/`sendStream` ok,
+     *     `sendToolResult*` throws (no outstanding call to resolve)
+     *   - count === 1 → `send`/`sendStream` throw; `sendToolResult*` ok
+     *   - count >  1 → every entry point throws (fan-out unservable)
+     *
+     * See `assertCanSendPlain` / `assertCanSendToolResult` for the full
+     * rationale.
+     */
+    private recordToolCallFanout;
+    /**
+     * Merge default + per-call config and force `reuseCache: true`.
+     * The session path is a session-reuse operation by construction —
+     * `reuseCache: false` on the continue path would wipe the very
+     * cache the delta depends on.
+     *
+     * MTP auto-default: if neither `defaultConfig` nor `overlay`
+     * sets `enableMtp` AND the underlying model exposes
+     * `hasMtpWeights()` returning `true`, set `enableMtp = true` so the
+     * speculative-decode path runs out of the box on MTP-capable
+     * checkpoints. An explicit `false` from either source wins (the
+     * undefined-check below preserves it). This duck-typed check also
+     * covers Gemma4 with an external draft attached — DSpark or Google
+     * assistant (`hasMtpWeights()` reports the external draft there,
+     * not in-checkpoint MTP heads).
+     */
+    private mergeConfig;
+    /**
+     * Render the exact full prompt and constrain generation to the physical KV
+     * window before native code allocates a block. Models that do not expose
+     * both the tokenizer seam and a load-time context snapshot retain their
+     * existing behavior.
+     *
+     * The returned config is a copy only when `maxNewTokens` needs clamping.
+     * An omitted output budget stays omitted when the native default fits; it is
+     * made explicit only when the remaining window is smaller than that default.
+     */
+    private constrainToContextCapacity;
+    /** Full history that a pending user/tool turn would render, without mutation. */
+    private historyWithPending;
+    /**
+     * Shared start-path logic for `send()`. Handles both the turn-0
+     * first-ever-send case and the image-change mid-session restart
+     * case. The image-change restart preserves prior history so the
+     * native side gets the full conversation re-rendered with the new
+     * image set.
+     */
+    private runStartPath;
+    /**
+     * Core of {@link runStartPath} that takes a PRE-BUILT pending
+     * `ChatMessage` (user or tool) instead of building a user message
+     * itself. The cold-restart catch in `sendToolResult()` replays the
+     * conversation through this core with a pending `{ role: 'tool', ... }`
+     * message so the tool-result turn is re-rendered against the full
+     * history without duplicating the start-path bookkeeping.
+     */
+    private runStartPathWithMessage;
+    /** Streaming counterpart to {@link runStartPath}. */
+    private runStartStreamPath;
+    /**
+     * Streaming counterpart to {@link runStartPathWithMessage}: replays
+     * through the cold start stream from a PRE-BUILT pending
+     * `ChatMessage`. The cold-restart catch in `sendToolResultStream()`
+     * delegates here with a pending `{ role: 'tool', ... }` message.
+     */
+    private runStartStreamPathWithMessage;
+    /**
+     * Shared pre-start bookkeeping for both `send()` and `sendStream()`:
+     *
+     *   - On an image-change restart (turn >= 1), reset the native KV
+     *     caches so the new image set gets a fresh prefill. History is
+     *     intentionally preserved — `chatSessionStart` receives the full
+     *     accumulated conversation plus the new user turn so the jinja
+     *     render walks every prior turn and every prior image again
+     *     (see plan's Turn 3 example: "full jinja on 3-turn history +
+     *     image B"). `lastImagesKey` will be overwritten by the
+     *     successful start path right after, and `turnCount` is
+     *     incremented by the start path the same way as for any other
+     *     turn.
+     *   - On a fresh / reset history, re-inject the system prompt.
+     */
+    private prepareStartPath;
+    /** Build a user `ChatMessage` with or without attached images/audio. */
+    private buildUserMessage;
+    /**
+     * Walk the history backward to find the most recent user message
+     * with images and return its SHA-256 key. Used by
+     * {@link startFromHistory} and {@link startFromHistoryStream} to
+     * hydrate `lastImagesKey` after a cold replay, so subsequent delta
+     * continues correctly detect image changes.
+     */
+    private computeTrailingImagesKey;
+    /**
+     * Audio counterpart of {@link computeTrailingImagesKey}: walk history
+     * backward to the most recent user message carrying audio and return its
+     * SHA-256 key, so a cold replay hydrates `lastAudioKey` correctly.
+     */
+    private computeTrailingAudioKey;
+    /**
+     * Derive the post-prime value of `unresolvedOkToolCallCount` from
+     * the primed history. Walks backward to the most recent assistant
+     * turn, then walks forward from that assistant to the end of history
+     * subtracting any `tool:` message that references one of the turn's
+     * `call_id`s. A fully-resolved history (every outstanding id matched
+     * by a sibling `tool:` message) returns `null`; any leftover count is
+     * the number of still-unresolved tool calls.
+     *
+     * Matches the runtime `recordToolCallFanout` semantics on the hot
+     * path: zero unresolved → `null` (no pending obligation); one →
+     * `1` (servable via `sendToolResult*()` only); two or more → the
+     * count itself (unservable fan-out — must be resolved via cold
+     * replay). The distinction between "ok" vs. other statuses only
+     * exists in the live `ToolCallResult[]` emitted by the native side —
+     * the persisted `ChatMessage.toolCalls` on an assistant message only
+     * carries successfully parsed calls (i.e. what would have been "ok"
+     * in the original live turn), so counting the array length is
+     * equivalent. Tool calls whose `id` is missing or empty can't be
+     * matched against subsequent `tool_call_id`s, so in that case we
+     * fall back to returning the raw `calls.length` (err safe).
+     */
+    private computeTrailingAssistantUnresolvedToolCallCount;
+}
+//# sourceMappingURL=chat-session.d.ts.map