@mlx-node/lm 0.0.5 → 0.0.7

package/dist/stream.js

@@ -1,19 +1,86 @@
-import { Qwen35Model as Qwen35ModelNative, Qwen35MoeModel as Qwen35MoeModelNative } from '@mlx-node/core';
-// Save references to the native callback-based methods before we override them
+import { Gemma4Model as Gemma4ModelNative, Lfm2Model as Lfm2ModelNative, Qwen3Model as Qwen3ModelNative, Qwen35Model as Qwen35ModelNative, Qwen35MoeModel as Qwen35MoeModelNative, } from '@mlx-node/core';
+// Save references to the native callback-based session streaming methods
+// before we override them. The legacy `chatStream` surface was removed in
+// the chat-session refactor; the remaining session entry points below
+// drive all streaming via the `ChatSession` API.
+//
+// Each wrapper class re-declares these three methods as
+// `AsyncGenerator<ChatStreamEvent>` overrides that delegate through the
+// shared `_runChatStream` bridge, so the wrapper structurally satisfies
+// `SessionCapableModel` and can be passed to `ChatSession<M>`.
+// Dense
 // oxlint-disable-next-line @typescript-eslint/unbound-method
-const _nativeDenseChatStream = Qwen35ModelNative.prototype.chatStream;
+const _nativeDenseChatStreamSessionStart = Qwen35ModelNative.prototype.chatStreamSessionStart;
 // oxlint-disable-next-line @typescript-eslint/unbound-method
-const _nativeMoeChatStream = Qwen35MoeModelNative.prototype.chatStream;
+const _nativeDenseChatStreamSessionContinue = Qwen35ModelNative.prototype.chatStreamSessionContinue;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeDenseChatStreamSessionContinueTool = Qwen35ModelNative.prototype.chatStreamSessionContinueTool;
+// MoE
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeMoeChatStreamSessionStart = Qwen35MoeModelNative.prototype.chatStreamSessionStart;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeMoeChatStreamSessionContinue = Qwen35MoeModelNative.prototype.chatStreamSessionContinue;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeMoeChatStreamSessionContinueTool = Qwen35MoeModelNative.prototype.chatStreamSessionContinueTool;
+// LFM2
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeLfm2ChatStreamSessionStart = Lfm2ModelNative.prototype.chatStreamSessionStart;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeLfm2ChatStreamSessionContinue = Lfm2ModelNative.prototype.chatStreamSessionContinue;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeLfm2ChatStreamSessionContinueTool = Lfm2ModelNative.prototype.chatStreamSessionContinueTool;
+// Gemma4
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeGemma4ChatStreamSessionStart = Gemma4ModelNative.prototype.chatStreamSessionStart;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeGemma4ChatStreamSessionContinue = Gemma4ModelNative.prototype.chatStreamSessionContinue;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeGemma4ChatStreamSessionContinueTool = Gemma4ModelNative.prototype.chatStreamSessionContinueTool;
+// Qwen3 (legacy, text-only)
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeQwen3ChatStreamSessionStart = Qwen3ModelNative.prototype.chatStreamSessionStart;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeQwen3ChatStreamSessionContinue = Qwen3ModelNative.prototype.chatStreamSessionContinue;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeQwen3ChatStreamSessionContinueTool = Qwen3ModelNative.prototype.chatStreamSessionContinueTool;
 /**
- * Shared AsyncGenerator implementation that wraps a native callback-based
- * chatStream into a `for await...of`-compatible stream.
+ * Shared AsyncGenerator adapter for callback-based native streaming methods.
+ *
+ * Takes a `startCall` closure that, given the JS-side callback, dispatches
+ * the underlying native stream (whatever method signature that is — the
+ * closure captures `messages` / `config` / `userMessage` etc) and resolves
+ * with a `ChatStreamHandle`. The generator pumps the resulting chunk queue,
+ * transforms each chunk into a `ChatStreamEvent`, and calls `handle.cancel()`
+ * in a `finally` block so early termination (user `break`, exception) still
+ * cleans up native state.
+ *
+ * ## Signal-driven fast-abort
+ *
+ * When an optional `AbortSignal` is supplied and fires, the adapter:
+ *   1. Calls `handle.cancel()` immediately so the native decode stops
+ *      on the next safepoint rather than running to completion.
+ *   2. Wakes the pending `waitForItem()` await by pushing a synthetic
+ *      "aborted" marker into the queue and calling `notify()`. Without
+ *      this wake-up the generator would stay parked on the `await`
+ *      until the next native chunk arrived, which on a fast-abort
+ *      path (client disconnect before first token) never happens.
+ *   3. The generator sees the marker, breaks out of its loop, and the
+ *      finally block runs `cancelOnce()` — which is a no-op because
+ *      `triggerAbort` already flipped the `cancelled` flag. Some
+ *      backends throw on double-cancel, so routing every cancel site
+ *      through `cancelOnce` keeps abort behavior deterministic.
  *
- * Cancellation is automatic via the generator's `finally` block.
+ * The finally block is also the landing site for the consumer calling
+ * `.return()` on the outer generator — the existing `yield` cleanup
+ * covers that case. Signal-driven abort covers the window where the
+ * consumer cannot reach `.return()` because they are blocked waiting
+ * for the very `yield` that `waitForItem()` is gating.
+ *
+ * @internal Exported so the VLM wrapper (`@mlx-node/vlm`) can reuse the
+ * exact same bridge without duplicating the plumbing. Not part of the
+ * public API — may change without notice.
  */
-/** @internal Exported for testing only. */
-export async function* _createChatStream(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-nativeMethod, self, messages, config) {
+export async function* _runChatStream(startCall, signal) {
     const queue = [];
     let resolve = null;
     const waitForItem = () => queue.length > 0
@@ -32,12 +99,74 @@ nativeMethod, self, messages, config) {
         queue.push(err ? { error: err } : { chunk });
         notify();
     };
-    const handle = await nativeMethod.call(self, messages, config ?? null, callback);
+    const handle = await startCall(callback);
+    // Guard against double-cancel. Some native backends throw on a
+    // second `cancel()`; we route every cancel site through this
+    // helper so the abort path (via `triggerAbort`) and the unwind
+    // path (via the `finally` block) don't cancel twice and so any
+    // backend that does throw is swallowed rather than escaping as
+    // an error out of an otherwise-clean early termination.
+    let cancelled = false;
+    const cancelOnce = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        try {
+            handle.cancel();
+        }
+        catch {
+            // Native backend threw on cancel — nothing actionable here.
+            // Swallow so aborted streams still surface as a clean early
+            // termination via the synthetic `aborted` marker rather than
+            // as an unexpected error out of the generator.
+        }
+    };
+    // Signal-driven fast-abort. If the signal is already aborted at
+    // attach time we still arm the listener so the synchronous abort
+    // dispatch path runs below (calling `handle.cancel()` after the
+    // handle is in hand, not before — there is nothing to cancel
+    // pre-start). For an already-fired signal Node delivers the
+    // `'abort'` event on the next microtask.
+    let onAbort = null;
+    if (signal != null) {
+        const triggerAbort = () => {
+            // Cancel the native side first so any work-in-flight winds
+            // down ASAP. `cancelOnce` is idempotent — the finally block
+            // will invoke it again after the generator unwinds, but the
+            // second call becomes a no-op.
+            cancelOnce();
+            // Push a synthetic abort marker so the consumer-visible
+            // generator breaks out of its loop at the next iteration
+            // rather than waiting for a native chunk that will never
+            // arrive (e.g. client disconnect before first token).
+            queue.push({ aborted: true });
+            notify();
+        };
+        if (signal.aborted) {
+            // Signal already fired before we could attach — dispatch
+            // synchronously so the waitForItem below resolves immediately.
+            triggerAbort();
+        }
+        else {
+            onAbort = triggerAbort;
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    }
     try {
-        while (true) {
+        loop: while (true) {
             await waitForItem();
             while (queue.length > 0) {
                 const item = queue.shift();
+                if (item.aborted) {
+                    // Consumer asked us to stop before the next chunk landed.
+                    // Break out so the finally block runs `handle.cancel()`
+                    // (idempotent — `triggerAbort` already called it) and the
+                    // consumer-side `for await` unblocks cleanly. We do NOT
+                    // throw an AbortError: callers (e.g. server endpoints that
+                    // flag client disconnect) have already decided this is not
+                    // an error from their perspective, just an early stop.
+                    break loop;
+                }
                 if (item.error)
                     throw item.error;
                 const chunk = item.chunk;
@@ -49,29 +178,38 @@ nativeMethod, self, messages, config) {
                         toolCalls: chunk.toolCalls ?? [],
                         thinking: chunk.thinking ?? null,
                         numTokens: chunk.numTokens,
+                        promptTokens: chunk.promptTokens ?? 0,
+                        reasoningTokens: chunk.reasoningTokens ?? 0,
                         rawText: chunk.rawText,
                         performance: chunk.performance ?? undefined,
                     };
                     return;
                 }
-                yield { text: chunk.text, done: false };
+                yield { text: chunk.text, done: false, isReasoning: chunk.isReasoning ?? undefined };
             }
         }
     }
     finally {
-        handle.cancel();
+        if (signal != null && onAbort != null) {
+            try {
+                signal.removeEventListener('abort', onAbort);
+            }
+            catch {
+                // removeEventListener shouldn't throw, but stay defensive —
+                // a misbehaving signal must not leak out of the finally.
+            }
+        }
+        cancelOnce();
     }
 }
 /**
- * Qwen3.5 dense model with AsyncGenerator-based `chatStream()`.
+ * Qwen3.5 dense model with AsyncGenerator-based session streaming.
  *
- * @example
- * ```typescript
- * const model = await Qwen35Model.load('./models/qwen3.5-3b');
- * for await (const event of model.chatStream(messages)) {
- *   if (!event.done) process.stdout.write(event.text);
- * }
- * ```
+ * Streaming is driven through the session API — `chatStreamSessionStart`,
+ * `chatStreamSessionContinue`, and `chatStreamSessionContinueTool` below —
+ * which adapt the callback-based native methods to
+ * `AsyncGenerator<ChatStreamEvent>` so the wrapper structurally satisfies
+ * `SessionCapableModel` and can be passed to `ChatSession<Qwen35Model>`.
  */
 export class Qwen35Model extends Qwen35ModelNative {
     static async load(modelPath) {
@@ -79,21 +217,62 @@ export class Qwen35Model extends Qwen35ModelNative {
         Object.setPrototypeOf(instance, Qwen35Model.prototype);
         return instance;
     }
-    // @ts-expect-error — override callback-based chatStream with AsyncGenerator
-    async *chatStream(messages, config) {
-        yield* _createChatStream(_nativeDenseChatStream, this, messages, config);
+    /**
+     * Streaming variant of {@link Qwen35Model#chatSessionStart}.
+     *
+     * Resets the KV caches, runs the jinja chat template, prefills on
+     * top of the fresh caches, and streams the decoded reply token-by-
+     * token. Stops on `<|im_end|>` so the cached history ends on a
+     * clean ChatML boundary that subsequent `chatStreamSessionContinue`
+     * deltas can append to. Text-only.
+     *
+     * The optional `signal` parameter wires an AbortSignal into the
+     * `_runChatStream` adapter's fast-abort path. Callers that need
+     * client-disconnect-aware cancellation (e.g. HTTP endpoints) pass
+     * one here and the native decode winds down at the next safepoint.
+     */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionStart(messages, config, signal) {
+        yield* _runChatStream((callback) => _nativeDenseChatStreamSessionStart.call(this, messages, config ?? null, callback), signal);
+    }
+    /**
+     * Streaming variant of {@link Qwen35Model#chatSessionContinue}.
+     *
+     * Builds a raw ChatML delta on top of the live session caches,
+     * tokenizes it, prefills the delta, and streams the decoded reply.
+     * Requires a live session started via `chatSessionStart` or
+     * `chatStreamSessionStart`. Stops on `<|im_end|>`.
+     *
+     * `images` is the native opt-in guard parameter — callers that
+     * attach a new image set must restart the session via
+     * `chatStreamSessionStart` with the full history. The high-level
+     * `ChatSession` wrapper handles that routing; callers that drive
+     * the wrapper directly should pass `null` for text-only continues.
+     */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinue(userMessage, images, config, signal) {
+        yield* _runChatStream((callback) => _nativeDenseChatStreamSessionContinue.call(this, userMessage, images, config ?? null, callback), signal);
+    }
+    /**
+     * Streaming variant of {@link Qwen35Model#chatSessionContinueTool}.
+     *
+     * Builds a ChatML `<tool_response>` delta on top of the live
+     * session caches and streams the decoded assistant reply. Requires
+     * a live session started via `chatSessionStart` /
+     * `chatStreamSessionStart`.
+     */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinueTool(toolCallId, content, config, signal) {
+        yield* _runChatStream((callback) => _nativeDenseChatStreamSessionContinueTool.call(this, toolCallId, content, config ?? null, callback), signal);
     }
 }
 /**
- * Qwen3.5 MoE model with AsyncGenerator-based `chatStream()`.
+ * Qwen3.5 MoE model wrapper.
  *
- * @example
- * ```typescript
- * const model = await Qwen35MoeModel.load('./models/qwen3.5-moe');
- * for await (const event of model.chatStream(messages)) {
- *   if (!event.done) process.stdout.write(event.text);
- * }
- * ```
+ * Streaming is driven through the `ChatSession` API — overrides below
+ * adapt the callback-based native methods to
+ * `AsyncGenerator<ChatStreamEvent>` so the wrapper structurally
+ * satisfies `SessionCapableModel`.
  */
 export class Qwen35MoeModel extends Qwen35MoeModelNative {
     static async load(modelPath) {
@@ -101,8 +280,138 @@ export class Qwen35MoeModel extends Qwen35MoeModelNative {
         Object.setPrototypeOf(instance, Qwen35MoeModel.prototype);
         return instance;
     }
-    // @ts-expect-error — override callback-based chatStream with AsyncGenerator
-    async *chatStream(messages, config) {
-        yield* _createChatStream(_nativeMoeChatStream, this, messages, config);
+    /** Streaming variant of {@link Qwen35MoeModel#chatSessionStart}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionStart(messages, config, signal) {
+        yield* _runChatStream((callback) => _nativeMoeChatStreamSessionStart.call(this, messages, config ?? null, callback), signal);
+    }
+    /** Streaming variant of {@link Qwen35MoeModel#chatSessionContinue}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinue(userMessage, images, config, signal) {
+        yield* _runChatStream((callback) => _nativeMoeChatStreamSessionContinue.call(this, userMessage, images, config ?? null, callback), signal);
+    }
+    /** Streaming variant of {@link Qwen35MoeModel#chatSessionContinueTool}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinueTool(toolCallId, content, config, signal) {
+        yield* _runChatStream((callback) => _nativeMoeChatStreamSessionContinueTool.call(this, toolCallId, content, config ?? null, callback), signal);
+    }
+}
+/**
+ * LFM2 model wrapper.
+ *
+ * Streaming is driven through the `ChatSession` API — overrides below
+ * adapt the callback-based native methods to
+ * `AsyncGenerator<ChatStreamEvent>` so the wrapper structurally
+ * satisfies `SessionCapableModel`. LFM2 is text-only; the native
+ * `images` guard rejects non-empty image sets with an
+ * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` prefix.
+ */
+export class Lfm2Model extends Lfm2ModelNative {
+    static async load(modelPath) {
+        const instance = await Lfm2ModelNative.load(modelPath);
+        Object.setPrototypeOf(instance, Lfm2Model.prototype);
+        return instance;
+    }
+    /** Streaming variant of {@link Lfm2Model#chatSessionStart}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionStart(messages, config, signal) {
+        yield* _runChatStream((callback) => _nativeLfm2ChatStreamSessionStart.call(this, messages, config ?? null, callback), signal);
     }
+    /** Streaming variant of {@link Lfm2Model#chatSessionContinue}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinue(userMessage, images, config, signal) {
+        yield* _runChatStream((callback) => _nativeLfm2ChatStreamSessionContinue.call(this, userMessage, images, config ?? null, callback), signal);
+    }
+    /** Streaming variant of {@link Lfm2Model#chatSessionContinueTool}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinueTool(toolCallId, content, config, signal) {
+        yield* _runChatStream((callback) => _nativeLfm2ChatStreamSessionContinueTool.call(this, toolCallId, content, config ?? null, callback), signal);
+    }
+}
+/**
+ * Gemma4 model wrapper.
+ *
+ * Streaming is driven through the `ChatSession` API — overrides below
+ * adapt the callback-based native methods to
+ * `AsyncGenerator<ChatStreamEvent>` so the wrapper structurally
+ * satisfies `SessionCapableModel`. Gemma4 is text-only in the
+ * current refactor scope; the native `images` guard rejects non-empty
+ * image sets with an `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` prefix.
+ */
+export class Gemma4Model extends Gemma4ModelNative {
+    static async load(modelPath) {
+        const instance = await Gemma4ModelNative.load(modelPath);
+        Object.setPrototypeOf(instance, Gemma4Model.prototype);
+        return instance;
+    }
+    /** Streaming variant of {@link Gemma4Model#chatSessionStart}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionStart(messages, config, signal) {
+        yield* _runChatStream((callback) => _nativeGemma4ChatStreamSessionStart.call(this, messages, config ?? null, callback), signal);
+    }
+    /** Streaming variant of {@link Gemma4Model#chatSessionContinue}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinue(userMessage, images, config, signal) {
+        yield* _runChatStream((callback) => _nativeGemma4ChatStreamSessionContinue.call(this, userMessage, images, config ?? null, callback), signal);
+    }
+    /** Streaming variant of {@link Gemma4Model#chatSessionContinueTool}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinueTool(toolCallId, content, config, signal) {
+        yield* _runChatStream((callback) => _nativeGemma4ChatStreamSessionContinueTool.call(this, toolCallId, content, config ?? null, callback), signal);
+    }
+}
+/**
+ * Qwen3 (legacy) model wrapper.
+ *
+ * Streaming is driven through the `ChatSession` API — overrides below
+ * adapt the callback-based native methods to
+ * `AsyncGenerator<ChatStreamEvent>` so the wrapper structurally
+ * satisfies `SessionCapableModel`. Qwen3 legacy is text-only; the
+ * native `images` guard rejects non-empty image sets with an
+ * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` prefix.
+ */
+export class Qwen3Model extends Qwen3ModelNative {
+    static async load(modelPath) {
+        const instance = await Qwen3ModelNative.load(modelPath);
+        Object.setPrototypeOf(instance, Qwen3Model.prototype);
+        return instance;
+    }
+    /** Streaming variant of {@link Qwen3Model#chatSessionStart}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionStart(messages, config, signal) {
+        yield* _runChatStream((callback) => _nativeQwen3ChatStreamSessionStart.call(this, messages, config ?? null, callback), signal);
+    }
+    /** Streaming variant of {@link Qwen3Model#chatSessionContinue}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinue(userMessage, images, config, signal) {
+        yield* _runChatStream((callback) => _nativeQwen3ChatStreamSessionContinue.call(this, userMessage, images, config ?? null, callback), signal);
+    }
+    /** Streaming variant of {@link Qwen3Model#chatSessionContinueTool}. */
+    // @ts-expect-error — override callback-based native method with AsyncGenerator
+    async *chatStreamSessionContinueTool(toolCallId, content, config, signal) {
+        yield* _runChatStream((callback) => _nativeQwen3ChatStreamSessionContinueTool.call(this, toolCallId, content, config ?? null, callback), signal);
+    }
+}
+// -------------------------------------------------------------------
+// Compile-time conformance check
+// -------------------------------------------------------------------
+//
+// Ensures each wrapper class structurally satisfies
+// `SessionCapableModel` so `ChatSession<XxxModel>` will type-check in
+// downstream code. The assignments are compile-only — the
+// `null as unknown as T` placeholder never runs. If a wrapper's
+// override signature drifts away from the interface, TypeScript will
+// fail to compile this block, surfacing the regression at build time.
+function _assertSessionCapable() {
+    const _qwen35 = null;
+    const _moe = null;
+    const _lfm2 = null;
+    const _gemma4 = null;
+    const _qwen3 = null;
+    void _qwen35;
+    void _moe;
+    void _lfm2;
+    void _gemma4;
+    void _qwen3;
 }
+void _assertSessionCapable;

package/dist/tools/index.d.ts

@@ -1,27 +1,54 @@
 /**
- * Tool calling utilities for Qwen3
+ * Tool calling utilities
  *
- * Provides types and helpers for working with tool/function calling in the chat() API.
+ * Provides types and helpers for working with tool/function calling
+ * through the `ChatSession` API. Tools are passed via `ChatConfig.tools`
+ * on `session.send()`, and a tool result is fed back through
+ * `session.sendToolResult()`.
+ *
+ * **Single tool call per assistant turn.** Each `sendToolResult(...)`
+ * call appends one tool message and immediately re-opens the assistant
+ * turn, so the session API only supports assistant turns that emit
+ * exactly one tool call. If the model emits multiple tool calls in a
+ * single turn, the caller must treat that as an unsupported state:
+ * throw, surface an error to the user, or tighten the system prompt /
+ * tool spec so the model produces at most one call per turn. Do **not**
+ * loop `sendToolResult` across the remaining calls — later results
+ * would be interleaved with a new assistant reply from the first, and
+ * the conversation state would become inconsistent (especially for
+ * stateful tools whose effects must land in order).
  *
  * @example
  * ```typescript
- * import { createToolDefinition, formatToolResponse } from '@mlx-node/lm';
+ * import { createToolDefinition, loadSession } from '@mlx-node/lm';
  *
  * const weatherTool = createToolDefinition(
  *   'get_weather',
  *   'Get weather for a location',
  *   { location: { type: 'string', description: 'City name' } },
- *   ['location']
+ *   ['location'],
  * );
  *
- * const result = await model.chat(messages, { tools: [weatherTool] });
+ * const session = await loadSession('./my-model');
+ *
+ * const result = await session.send('What is the weather in Tokyo?', {
+ *   config: { tools: [weatherTool] },
+ * });
  *
- * for (const call of result.toolCalls) {
- *   if (call.status === 'ok') {
- *     const toolResult = await executeMyTool(call.name, call.arguments);
- *     // Continue conversation with tool result
- *     messages.push({ role: 'user', content: formatToolResponse(toolResult) });
- *   }
+ * const okCalls = result.toolCalls.filter((c) => c.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 = await executeMyTool(call.name, call.arguments);
+ *   const followUp = await session.sendToolResult(call.id, JSON.stringify(toolOutput), {
+ *     config: { tools: [weatherTool] },
+ *   });
+ *   console.log(followUp.text);
  * }
  * ```
  *

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,cAAc,YAAY,CAAC"}

package/dist/tools/index.js

@@ -1,27 +1,54 @@
 /**
- * Tool calling utilities for Qwen3
+ * Tool calling utilities
  *
- * Provides types and helpers for working with tool/function calling in the chat() API.
+ * Provides types and helpers for working with tool/function calling
+ * through the `ChatSession` API. Tools are passed via `ChatConfig.tools`
+ * on `session.send()`, and a tool result is fed back through
+ * `session.sendToolResult()`.
+ *
+ * **Single tool call per assistant turn.** Each `sendToolResult(...)`
+ * call appends one tool message and immediately re-opens the assistant
+ * turn, so the session API only supports assistant turns that emit
+ * exactly one tool call. If the model emits multiple tool calls in a
+ * single turn, the caller must treat that as an unsupported state:
+ * throw, surface an error to the user, or tighten the system prompt /
+ * tool spec so the model produces at most one call per turn. Do **not**
+ * loop `sendToolResult` across the remaining calls — later results
+ * would be interleaved with a new assistant reply from the first, and
+ * the conversation state would become inconsistent (especially for
+ * stateful tools whose effects must land in order).
  *
  * @example
  * ```typescript
- * import { createToolDefinition, formatToolResponse } from '@mlx-node/lm';
+ * import { createToolDefinition, loadSession } from '@mlx-node/lm';
  *
  * const weatherTool = createToolDefinition(
  *   'get_weather',
  *   'Get weather for a location',
  *   { location: { type: 'string', description: 'City name' } },
- *   ['location']
+ *   ['location'],
  * );
  *
- * const result = await model.chat(messages, { tools: [weatherTool] });
+ * const session = await loadSession('./my-model');
+ *
+ * const result = await session.send('What is the weather in Tokyo?', {
+ *   config: { tools: [weatherTool] },
+ * });
  *
- * for (const call of result.toolCalls) {
- *   if (call.status === 'ok') {
- *     const toolResult = await executeMyTool(call.name, call.arguments);
- *     // Continue conversation with tool result
- *     messages.push({ role: 'user', content: formatToolResponse(toolResult) });
- *   }
+ * const okCalls = result.toolCalls.filter((c) => c.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 = await executeMyTool(call.name, call.arguments);
+ *   const followUp = await session.sendToolResult(call.id, JSON.stringify(toolOutput), {
+ *     config: { tools: [weatherTool] },
+ *   });
+ *   console.log(followUp.text);
  * }
  * ```
  *

package/dist/tools/types.d.ts

@@ -164,7 +164,8 @@ export interface ApplyChatTemplateOptions {
  * @param description - Description of what the function does
  * @param properties - Object defining the function parameters (will be JSON stringified)
  * @param required - Array of required parameter names
- * @returns A properly formatted ToolDefinition ready for use with model.chat()
+ * @returns A properly formatted ToolDefinition ready to pass via `ChatConfig.tools`
+ *   on `ChatSession.send()` / `sendToolResult()`.
  *
  * @example
  * ```typescript
@@ -173,34 +174,13 @@ export interface ApplyChatTemplateOptions {
  *   'Get weather information for a location',
  *   {
  *     location: { type: 'string', description: 'City name' },
- *     units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
+ *     units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
  *   },
- *   ['location']
+ *   ['location'],
  * );
  *
- * const result = await model.chat(messages, { tools: [weatherTool] });
+ * const result = await session.send(userPrompt, { config: { tools: [weatherTool] } });
  * ```
  */
 export declare function createToolDefinition(name: string, description?: string, properties?: Record<string, FunctionParameterProperty>, required?: string[]): ToolDefinition;
-/**
- * Format a tool response for inclusion in a message
- *
- * Creates a properly formatted tool response string that can be used
- * in tool messages when continuing a conversation after a tool call.
- *
- * @param content - The response content (will be JSON stringified if object)
- * @returns Formatted tool response string wrapped in `<tool_response>` tags
- *
- * @example
- * ```typescript
- * // After executing a tool call from model.chat()
- * const toolResult = await executeMyTool(call.arguments);
- * const responseMessage = {
- *   role: 'user',
- *   content: formatToolResponse(toolResult)
- * };
- * const finalResult = await model.chat([...messages, responseMessage]);
- * ```
- */
-export declare function formatToolResponse(content: unknown): string;
 //# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC;AAElC;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,IAAI,EAAE,QAAQ,CAAC;IACf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,IAAI,EAAE,QAAQ,CAAC;IACf,0BAA0B;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mBAAmB;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,qDAAqD;IACrD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACtD,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAehB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAK3D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC;AAElC;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,IAAI,EAAE,QAAQ,CAAC;IACf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,IAAI,EAAE,QAAQ,CAAC;IACf,0BAA0B;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mBAAmB;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,qDAAqD;IACrD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACtD,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAehB"}