@mlx-node/lm 0.0.5 → 0.0.7

package/README.md

@@ -1,6 +1,6 @@
 # @mlx-node/lm
 
-High-level language model inference for Node.js on Apple Silicon. Supports Qwen3 and Qwen3.5 (Dense and MoE) with streaming, tool calling, and profiling — all running locally on Metal GPU.
+High-level language model inference for Node.js on Apple Silicon. Supports Qwen3, Qwen3.5 (Dense and MoE), LFM2, and Gemma4 with streaming, multi-turn chat sessions, tool calling, and profiling — all running locally on Metal GPU.
 
 ## Requirements
 
@@ -15,26 +15,31 @@ npm install @mlx-node/lm
 
 ## Quick Start
 
-```typescript
-import { loadModel } from '@mlx-node/lm';
+Multi-turn chat runs through `ChatSession`, which owns the server-side KV cache and hides the session bookkeeping behind `send()` / `sendStream()`. The `loadSession()` convenience wrapper loads the model and constructs the session in one step:
 
-const model = await loadModel('./models/Qwen3-0.6B');
+```typescript
+import { loadSession } from '@mlx-node/lm';
 
-const result = model.chat([{ role: 'user', content: 'What is the capital of France?' }]);
+const session = await loadSession('./models/Qwen3-0.6B');
 
+const result = await session.send('What is the capital of France?');
 console.log(result.text);
+
+// Follow-ups reuse the live KV cache — no prompt replay.
+const followUp = await session.send('And its population?');
+console.log(followUp.text);
 ```
 
 ## Streaming
 
-Qwen3.5 models support token-by-token streaming via `AsyncGenerator`:
+Every generative model wrapper supports token-by-token streaming via `session.sendStream()`, which yields an `AsyncGenerator<ChatStreamEvent>`:
 
 ```typescript
-import { loadModel } from '@mlx-node/lm';
+import { loadSession } from '@mlx-node/lm';
 
-const model = await loadModel('./models/Qwen3.5-0.6B');
+const session = await loadSession('./models/Qwen3.5-0.8B');
 
-for await (const event of model.chatStream(messages, config)) {
+for await (const event of session.sendStream('Write a haiku about TypeScript.')) {
   if (!event.done) {
     process.stdout.write(event.text);
   } else {
@@ -43,16 +48,16 @@ for await (const event of model.chatStream(messages, config)) {
 }
 ```
 
-Breaking out of the loop automatically cancels generation.
+Breaking out of the loop automatically cancels generation. The session tracks its turn state so the next `send()` / `sendStream()` continues the same conversation against the live cache.
 
 ## Tool Calling
 
-OpenAI-compatible function calling with `createToolDefinition`:
+OpenAI-compatible function calling with `createToolDefinition`. Tool-result turns feed back through the same session via `sendToolResult()`, which dispatches a native `chatSessionContinueTool` against the live KV cache:
 
 ```typescript
-import { loadModel, createToolDefinition, formatToolResponse } from '@mlx-node/lm';
+import { loadSession, createToolDefinition } from '@mlx-node/lm';
 
-const model = await loadModel('./models/Qwen3-0.6B');
+const session = await loadSession('./models/Qwen3-0.6B');
 
 const tools = [
   createToolDefinition(
@@ -65,37 +70,52 @@ const tools = [
   ),
 ];
 
-const result = model.chat([{ role: 'user', content: 'What is the weather in Tokyo?' }], { tools });
-
-// If the model calls a tool, execute it and continue
-if (result.toolCalls?.length) {
-  const toolResult = executeMyTool(result.toolCalls[0]);
-  const followUp = model.chat(
-    [
-      ...messages,
-      { role: 'assistant', content: result.rawText },
-      { role: 'tool', content: formatToolResponse(toolResult) },
-    ],
-    { tools },
+const result = await session.send('What is the weather in Tokyo?', { config: { tools } });
+
+// The chat-session API only supports exactly one tool call per assistant turn:
+// each `sendToolResult` dispatch immediately re-opens the assistant turn, so
+// feeding a second result for the same turn would interleave a new assistant
+// reply between the two results. `ChatSession` enforces this at runtime — a
+// subsequent `sendToolResult*` after a multi-call turn throws with a clear
+// error — and the caller must refuse multi-call turns up front. Tighten the
+// prompt or tool spec so the model emits at most one call per turn.
+const okCalls = result.toolCalls?.filter((tc) => tc.status === 'ok') ?? [];
+if (okCalls.length > 1) {
+  throw new Error(
+    `ChatSession only supports one tool call per assistant turn; ` +
+      `model emitted ${okCalls.length}. Tighten the prompt or tool spec.`,
   );
 }
+const call = okCalls[0];
+if (call) {
+  const toolOutput = JSON.stringify(await executeMyTool(call));
+  const followUp = await session.sendToolResult(call.id, toolOutput, { config: { tools } });
+  console.log(followUp.text);
+}
 ```
 
 ## Model Loading
 
-`loadModel()` auto-detects the model architecture from `config.json`:
+`loadModel()` auto-detects the model architecture from `config.json`. Use `loadSession()` when you want an ergonomic `ChatSession` handle in one step, or load a concrete model class and construct `new ChatSession(model)` when you need a reference to both the model and the session (e.g. for `generate()` calls, training, or model metadata):
 
 ```typescript
-import { loadModel, Qwen35Model, Qwen35MoeModel } from '@mlx-node/lm';
+import { loadSession, ChatSession, Qwen35Model, Qwen35MoeModel } from '@mlx-node/lm';
 
-// Auto-detect (reads config.json model_type field)
-const model = await loadModel('./models/Qwen3-0.6B');
+// Convenience: auto-detect architecture and wrap in a ChatSession.
+const session = await loadSession('./models/Qwen3-0.6B', { system: 'Be concise.' });
 
-// Or load a specific architecture directly
+// Or load a specific architecture directly — every generative model wrapper
+// structurally satisfies ChatSession's SessionCapableModel bound.
 const dense = await Qwen35Model.load('./models/Qwen3.5-0.8B');
 const moe = await Qwen35MoeModel.load('./models/Qwen3.5-35B-A3B');
+const denseSession = new ChatSession(dense);
+const moeSession = new ChatSession(moe);
 ```
 
+`loadSession()` rejects embedding models (`HarrierModel`) and the native `QianfanOCRModel` — for the VLM case, import `QianfanOCRModel` from `@mlx-node/vlm` and wrap it with `new ChatSession(...)` directly.
+
+`ChatSession` accepts an options bag with `{ system?, defaultConfig? }`. The system prompt is injected on the first turn and never re-sent. Per-call config passed to `send()` / `sendStream()` shallow-merges on top of `defaultConfig`. Call `session.reset()` to wipe the KV cache and start a fresh conversation.
+
 ### Pre-defined Configs
 
 ```typescript
@@ -104,8 +124,8 @@ import { QWEN3_CONFIGS, QWEN35_CONFIGS, getQwen3Config, getQwen35Config } from '
 // Available Qwen3 configs: 'qwen3-0.6b', 'qwen3-1.7b', 'qwen3-7b'
 const config = getQwen3Config('qwen3-0.6b');
 
-// Available Qwen3.5 configs: 'qwen3.5-0.8b'
-const config35 = getQwen35Config('qwen3.5-0.8b');
+// Available Qwen3.5 configs: 'qwen3.5-0.6b'
+const config35 = getQwen35Config('qwen3.5-0.6b');
 ```
 
 ## Profiling
@@ -128,12 +148,16 @@ Or set `MLX_PROFILE_DECODE=1` to auto-enable and write a report on exit.
 
 ### Classes
 
-| Class            | Description                                                                      |
-| ---------------- | -------------------------------------------------------------------------------- |
-| `loadModel()`    | Auto-detect and load any supported model from disk                               |
-| `Qwen3Model`     | Qwen3 inference — `generate()`, `chat()`, paged attention, speculative decoding  |
-| `Qwen35Model`    | Qwen3.5 Dense — `generate()`, `chat()`, `chatStream()` with compiled C++ forward |
-| `Qwen35MoeModel` | Qwen3.5 MoE — same API as Dense with expert routing                              |
+| Class            | Description                                                                       |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `loadModel()`    | Auto-detect and load any supported model from disk                                |
+| `loadSession()`  | `loadModel()` + `new ChatSession(model)` in one step                              |
+| `ChatSession<M>` | Multi-turn chat wrapper — `send()`, `sendStream()`, `sendToolResult()`, `reset()` |
+| `Qwen3Model`     | Qwen3 inference — `generate()`, paged attention, speculative decoding             |
+| `Qwen35Model`    | Qwen3.5 Dense — `generate()` with compiled C++ forward                            |
+| `Qwen35MoeModel` | Qwen3.5 MoE — `generate()` with compiled C++ forward and expert routing           |
+| `Gemma4Model`    | Gemma4 inference — `generate()`                                                   |
+| `Lfm2Model`      | LFM2.5 hybrid conv+attention inference — `generate()`                             |
 
 ### Streaming Types
 
@@ -179,8 +203,6 @@ function createToolDefinition(
   properties?: Record<string, FunctionParameterProperty>,
   required?: string[],
 ): ToolDefinition;
-
-function formatToolResponse(content: string): string;
 ```
 
 ### Functions
@@ -188,18 +210,21 @@ function formatToolResponse(content: string): string;
 | Function                 | Description                                          |
 | ------------------------ | ---------------------------------------------------- |
 | `createToolDefinition()` | Create an OpenAI-compatible tool definition          |
-| `formatToolResponse()`   | Wrap tool output in `<tool_response>` tags           |
 | `detectModelType()`      | Read `config.json` and return the `model_type` field |
 | `enableProfiling()`      | Start profiling with auto-report on exit             |
 | `disableProfiling()`     | Stop profiling and write JSON report                 |
 
 ## Supported Models
 
-| Model         | `chat()` | `chatStream()` | Training | Notes                                 |
-| ------------- | :------: | :------------: | :------: | ------------------------------------- |
-| Qwen3         |   Yes    |       No       | GRPO/SFT | Paged attention, speculative decoding |
-| Qwen3.5 Dense |   Yes    |      Yes       | GRPO/SFT | Compiled C++ forward, VLM variant     |
-| Qwen3.5 MoE   |   Yes    |      Yes       | GRPO/SFT | Compiled C++ forward, expert routing  |
+Every generative model wrapper exposes the same `ChatSession<M>` surface — `send()`, `sendStream()`, and `sendToolResult()` all work against any of the models below.
+
+| Model         | `generate()` | `ChatSession` | Training | Notes                                 |
+| ------------- | :----------: | :-----------: | :------: | ------------------------------------- |
+| Qwen3         |     Yes      |      Yes      | GRPO/SFT | Paged attention, speculative decoding |
+| Qwen3.5 Dense |     Yes      |      Yes      | GRPO/SFT | Compiled C++ forward, VLM variant     |
+| Qwen3.5 MoE   |     Yes      |      Yes      | GRPO/SFT | Compiled C++ forward, expert routing  |
+| Gemma4        |     Yes      |      Yes      |    No    | Streaming chat via session            |
+| LFM2.5        |     Yes      |      Yes      |    No    | Hybrid conv + attention architecture  |
 
 ## Performance
 

package/dist/chat-session.d.ts

@@ -0,0 +1,455 @@
+/**
+ * Generic server-side chat session wrapper.
+ *
+ * `ChatSession<M>` is the cross-model chat-session wrapper. It works
+ * against any model that exposes the uniform chat-session NAPI
+ * surface — `chatSessionStart`,
+ * `chatSessionContinue`, `chatSessionContinueTool`, and their
+ * streaming variants plus `resetCaches`. See `SessionCapableModel`
+ * below.
+ *
+ * Design notes:
+ *
+ *   - The session tracks its own `ChatMessage[]` history on the
+ *     TypeScript side. In the common text-continue case the history
+ *     is only appended to and never read back — each `send()` on
+ *     turn >= 1 issues a cheap `chatSessionContinue` delta against
+ *     the live KV cache. The history is kept purely so the
+ *     image-change mid-session path can call `chatSessionStart` with
+ *     the full rebuilt history for a clean re-prefill.
+ *
+ *   - An image hash (`lastImagesKey`) tracks the images bound to the
+ *     current cache. A `send()` call whose image set has changed
+ *     (different bytes or different ordering) triggers a full
+ *     restart: `resetCaches()` → push the new user message (with
+ *     images) to history → `chatSessionStart(history)`.
+ *
+ *   - Text-only `send()` on turn >= 1 takes the cheap delta path.
+ *
+ *   - `sendToolResult` always dispatches `chatSessionContinueTool`,
+ *     since tool turns never change image state. The session enforces
+ *     a strict unresolved-ok-tool-call contract at runtime, driven by
+ *     `unresolvedOkToolCallCount` (derived from `ChatResult.toolCalls`
+ *     after each turn via `countOkToolCalls` /
+ *     `computeTrailingAssistantUnresolvedToolCallCount`):
+ *
+ *       * `null` — the trailing assistant turn has no outstanding ok
+ *         tool call. Plain `send()` / `sendStream()` are the only
+ *         valid entry points; `sendToolResult*()` throws because
+ *         there is nothing for the result to resolve.
+ *       * `1` — exactly one outstanding ok tool call. Plain `send()` /
+ *         `sendStream()` throw (they would orphan the call);
+ *         `sendToolResult*()` is the sole valid forward step and
+ *         dispatches the tool result through the native session.
+ *       * `>1` — a multi-tool-call fan-out that the chat-session API
+ *         cannot progress incrementally (each `sendToolResult*` would
+ *         re-open the assistant turn and weave new replies between
+ *         the sibling results). Both `send()` / `sendStream()` and
+ *         `sendToolResult*()` throw. The only valid recovery is
+ *         `reset()` or `primeHistory()` + `startFromHistory*()` with
+ *         a fully-resolved conversation — there is no "advance past
+ *         the broken turn" path. This mirrors the native ChatML delta
+ *         format which would otherwise silently corrupt multi-call
+ *         conversations.
+ *
+ *   - `sawFinal` gates `turnCount` advance on the streaming path, so
+ *     the session refuses to advance when the stream throws
+ *     mid-decode or yields a final chunk with
+ *     `finishReason: 'error'`.
+ *
+ *   - The `inFlight` guard rejects concurrent `send()` /
+ *     `sendStream()` calls at the class level. The native side
+ *     serializes cache mutation on a single worker thread, so a
+ *     second in-flight call would race the first's cache-save step.
+ *
+ *   - **Cold-restart primitives.** `primeHistory()` plus
+ *     `startFromHistory()` / `startFromHistoryStream()` let a caller
+ *     seed a fresh session with an externally-reconstructed history
+ *     (e.g. a server `ResponseStore` chain) and replay it through the
+ *     native `chatSessionStart` path without going through `send()`.
+ *     These are intended for server-side `SessionRegistry` cache-miss
+ *     cold-start; normal usage stays on `send` / `sendStream` /
+ *     `sendToolResult` / `reset`.
+ *
+ * ## Typical usage
+ *
+ * ```typescript
+ * import { Qwen35Model, ChatSession } from '@mlx-node/lm';
+ *
+ * const model = await Qwen35Model.load('./models/qwen3.5-0.8b');
+ * const session = new ChatSession(model, { system: 'Be concise.' });
+ * const r1 = await session.send('Say hi in one word.');
+ * const r2 = await session.send('Another word?');
+ * await session.reset();
+ * ```
+ */
+import type { ChatConfig, ChatMessage, ChatResult } from '@mlx-node/core';
+import type { ChatStreamEvent } from './stream.js';
+/**
+ * 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 {
+    chatSessionStart(messages: ChatMessage[], config?: ChatConfig | null): Promise<ChatResult>;
+    chatSessionContinue(userMessage: string, images: Uint8Array[] | null, config?: ChatConfig | null): Promise<ChatResult>;
+    chatSessionContinueTool(toolCallId: string, content: string, config?: ChatConfig | 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, config?: ChatConfig | null, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
+    chatStreamSessionContinueTool(toolCallId: string, content: string, config?: ChatConfig | null, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
+    resetCaches(): void;
+}
+/** 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[];
+    /**
+     * Per-call `ChatConfig` overlay applied on top of the session's
+     * `defaultConfig`. `reuseCache` is always forced on regardless of
+     * what the caller passes.
+     */
+    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.
+     */
+    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 (FNV-1a 64-bit; see `computeImagesKey`).
+     * `null` when no images are cached. A `send()` whose new key
+     * differs triggers a full `chatSessionStart` restart.
+     */
+    private lastImagesKey;
+    private turnCount;
+    private inFlight;
+    /**
+     * 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;
+    /**
+     * 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.
+     *
+     * Appends a `{ role: 'tool', ... }` message to history on success.
+     */
+    sendToolResult(toolCallId: string, content: string, opts?: {
+        config?: ChatConfig;
+    }): Promise<ChatResult>;
+    /** Streaming variant of {@link ChatSession#sendToolResult}. */
+    sendToolResultStream(toolCallId: string, content: string, opts?: {
+        config?: ChatConfig;
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    private mergeConfig;
+    /**
+     * 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;
+    /** Streaming counterpart to {@link runStartPath}. */
+    private runStartStreamPath;
+    /**
+     * 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. */
+    private buildUserMessage;
+    /**
+     * Walk the history backward to find the most recent user message
+     * with images and return its FNV-1a 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;
+    /**
+     * 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