@mlx-node/server 0.0.13 → 0.0.15

package/dist/host/discover.d.ts

@@ -1,5 +1,5 @@
 /** Discover locally-downloaded generative models under a given directory. */
-import { type LaunchPreset, type ModelType } from '@mlx-node/lm';
+import type { LaunchPreset, ModelType } from '@mlx-node/lm/family-data';
 /** A locally-downloaded model paired with its sampling preset. */
 export interface DiscoveredModel {
     name: string;
@@ -8,11 +8,8 @@ export interface DiscoveredModel {
     preset: LaunchPreset;
 }
 /**
- * Scan `dir` for model subdirectories. Each subdirectory with a recognized
- * `config.json` is returned with its inferred `ModelType` and `LaunchPreset`.
- * Non-generative types are silently skipped. Entries with no preset or an
- * undetectable config are skipped (warnings only emitted when `MLX_DEBUG`
- * is set). Must stay cheap — do not load weights here.
+ * Use the same checkpoint IDs and paths as the agent and setup UI, including
+ * supported GGUF files and their quant variants. No weights are loaded here.
  */
 export declare function discoverModels(dir: string): Promise<DiscoveredModel[]>;
 //# sourceMappingURL=discover.d.ts.map

package/dist/host/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/host/discover.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAM7E,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAEtB,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAoC5E"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/host/discover.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAGxE,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAO5E"}

package/dist/host/discover.js

@@ -1,47 +1,14 @@
 /** Discover locally-downloaded generative models under a given directory. */
-import { readdir } from 'node:fs/promises';
-import { basename, join } from 'node:path';
-import { detectModelType, NON_GENERATIVE_FAMILY_IDS, launchPresetFor, } from '@mlx-node/lm';
+import { discoverLocalChatModels } from '@mlx-node/lm/model-discovery';
 /**
- * Scan `dir` for model subdirectories. Each subdirectory with a recognized
- * `config.json` is returned with its inferred `ModelType` and `LaunchPreset`.
- * Non-generative types are silently skipped. Entries with no preset or an
- * undetectable config are skipped (warnings only emitted when `MLX_DEBUG`
- * is set). Must stay cheap — do not load weights here.
+ * Use the same checkpoint IDs and paths as the agent and setup UI, including
+ * supported GGUF files and their quant variants. No weights are loaded here.
  */
 export async function discoverModels(dir) {
-    const debug = Boolean(process.env.MLX_DEBUG);
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const full = join(dir, entry.name);
-        let modelType;
-        try {
-            modelType = await detectModelType(full);
-        }
-        catch (err) {
-            if (debug)
-                console.warn(`[mlx] skip ${full}: ${err.message}`);
-            continue;
-        }
-        if (NON_GENERATIVE_FAMILY_IDS.has(modelType))
-            continue;
-        const preset = launchPresetFor(modelType);
-        if (!preset) {
-            if (debug)
-                console.warn(`[mlx] skip ${full}: no LAUNCH_PRESETS entry for ${modelType}`);
-            continue;
-        }
-        out.push({ name: basename(full), path: full, modelType, preset });
-    }
-    out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-    return out;
+    return (await discoverLocalChatModels(dir)).map(({ name, path, modelType, preset }) => ({
+        name,
+        path,
+        modelType,
+        preset,
+    }));
 }

package/dist/host/index.d.ts

@@ -38,7 +38,7 @@
  * after it.
  */
 import type { Server } from 'node:http';
-import { type LoadableModel } from '@mlx-node/lm';
+import { type LoadableModel, type LoadModelOptions } from '@mlx-node/lm';
 import type { ServerHealth } from '../health.js';
 import { type CloseOptions, type ServerInstance } from '../server.js';
 import { type DiscoveredModel } from './discover.js';
@@ -134,7 +134,7 @@ export interface InferenceHostOptions {
      */
     sweepOrphanTempRoots?: boolean;
     /** Test seam: replaces the native model loader. */
-    loadModel?: (path: string) => Promise<LoadableModel>;
+    loadModel?: (path: string, options?: LoadModelOptions) => Promise<LoadableModel>;
     /** Test seam: replaces the verbose request logger. */
     attachLogger?: (server: Server, logDir: string) => Logger;
 }

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

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

package/dist/host/index.js

@@ -38,6 +38,7 @@
  * after it.
  */
 import { loadModel as loadModelNative, PagedConfigOverrideManager, QWEN35_PAGED_MODEL_TYPES, } from '@mlx-node/lm';
+import { findDFlash2Draft } from '@mlx-node/lm/draft-companion';
 import { createServer, resolveAuthToken } from '../server.js';
 import { discoverModels } from './discover.js';
 import { applyEnginePolicy } from './env-policy.js';
@@ -178,7 +179,13 @@ export async function createInferenceHost(opts = {}) {
         tempDirPrefix: hostTempDirPrefix(),
     });
     const loadModelFn = opts.loadModel ?? loadModelNative;
-    const loadModelPagedAware = async (path) => loadModelFn(await pagedConfigOverrides.resolve(path));
+    const loadModelPagedAware = async (path) => {
+        const entry = models.find((model) => model.path === path);
+        // Resolve against the source directory before creating the paged config overlay.
+        const draftModelPath = findDFlash2Draft(path, entry.modelType, modelsDir);
+        const resolvedPath = await pagedConfigOverrides.resolve(path);
+        return draftModelPath === undefined ? loadModelFn(resolvedPath) : loadModelFn(resolvedPath, { draftModelPath });
+    };
     const controller = makeSwapController(models, server.registry, loadModelPagedAware, boundEntry.name);
     ctrlRef.current = controller;
     // Attach AFTER `createServer` so the wrapper sees every incoming request,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlx-node/server",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "homepage": "https://github.com/mlx-node/mlx-node",
   "bugs": {
     "url": "https://github.com/mlx-node/mlx-node/issues"
@@ -12,25 +12,30 @@
     "directory": "packages/server"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "@mlx-node/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./host": {
+      "@mlx-node/source": "./src/host/index.ts",
       "types": "./dist/host/index.d.ts",
       "import": "./dist/host/index.js"
     },
     "./host/env-policy": {
+      "@mlx-node/source": "./src/host/env-policy.ts",
       "types": "./dist/host/env-policy.d.ts",
       "import": "./dist/host/env-policy.js"
     },
     "./host/paths": {
+      "@mlx-node/source": "./src/host/paths.ts",
       "types": "./dist/host/paths.d.ts",
       "import": "./dist/host/paths.js"
     }
@@ -39,8 +44,8 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@mlx-node/core": "0.0.13",
-    "@mlx-node/lm": "0.0.13"
+    "@mlx-node/core": "0.0.15",
+    "@mlx-node/lm": "0.0.15"
   },
   "devDependencies": {
     "@types/node": "@types/node@26.4.0"

package/src/auth.ts

@@ -0,0 +1,111 @@
+/**
+ * Optional bearer-token gate.
+ *
+ * Enforced at the single choke point in `createHandler`'s returned closure —
+ * after the CORS/OPTIONS early-return, before `routeRequest` — so there is
+ * exactly one place a route can be added without inheriting the gate.
+ *
+ * Scope, deliberately narrow: this is a shared-secret check for a server
+ * bound to loopback and supervised by a local app. It is NOT a
+ * multi-tenant auth system — there is one token, no rotation, no scopes,
+ * no per-caller identity.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+/** `Bearer ` prefix length, used to slice the credential out of `authorization`. */
+const BEARER_PREFIX = 'bearer ';
+
+/**
+ * Extract the presented credential, or `null` when none is usable.
+ *
+ * `x-api-key` is checked FIRST because Anthropic clients (including Claude
+ * Code, the primary consumer of `/v1/messages`) send it. Checking it first
+ * also means a stale `authorization` header injected by an intermediary
+ * cannot shadow the caller's real key.
+ *
+ * Array-valued headers are rejected outright. Node collapses repeated
+ * non-allowlisted headers such as `x-api-key` into a `string[]`; joining or
+ * picking one arbitrarily would let a caller smuggle a second value past a
+ * front proxy that only inspected the first.
+ */
+export function extractPresentedToken(req: IncomingMessage): string | null {
+  const apiKey = req.headers['x-api-key'];
+  if (apiKey !== undefined) {
+    return typeof apiKey === 'string' ? apiKey : null;
+  }
+
+  const authorization = req.headers.authorization;
+  if (typeof authorization !== 'string') return null;
+  // Scheme is case-insensitive per RFC 7235; the credential is not.
+  if (authorization.length <= BEARER_PREFIX.length) return null;
+  if (authorization.slice(0, BEARER_PREFIX.length).toLowerCase() !== BEARER_PREFIX) return null;
+  return authorization.slice(BEARER_PREFIX.length);
+}
+
+/**
+ * Constant-time-ish credential comparison.
+ *
+ * The length check in front of `timingSafeEqual` is unavoidable — the
+ * primitive throws on mismatched lengths. It therefore LEAKS the length of
+ * the configured token to an attacker who can time responses. That is an
+ * accepted trade: the token is a locally-generated high-entropy secret, and
+ * knowing its length does not meaningfully reduce the search space. The
+ * byte-by-byte content comparison, which is the part that would otherwise
+ * allow incremental guessing, stays constant-time.
+ */
+export function tokensMatch(presented: string, expected: string): boolean {
+  // The empty string is not a credential, in either position. `timingSafeEqual`
+  // on two zero-length buffers returns TRUE, so a server misconfigured with an
+  // empty token would authenticate every caller who sent an empty `x-api-key`.
+  // `resolveAuthToken` rejects an empty token before it can reach a server built
+  // through `createServer`; this is the second latch, for a caller that
+  // constructs `createHandler` directly. Refusing is the fail-closed direction —
+  // an empty token 401s everything rather than admitting everything.
+  if (presented === '' || expected === '') return false;
+  const presentedBytes = Buffer.from(presented, 'utf8');
+  const expectedBytes = Buffer.from(expected, 'utf8');
+  if (presentedBytes.length !== expectedBytes.length) return false;
+  return timingSafeEqual(presentedBytes, expectedBytes);
+}
+
+/**
+ * `true` when the caller offered SOME credential, valid or not.
+ *
+ * Used only by the `/health` carve-out: an anonymous poll degrades to a
+ * liveness-only body, but a caller who presented a wrong (or malformed)
+ * credential gets a 401 so a mistyped token surfaces instead of masquerading
+ * as a healthy 200.
+ */
+export function hasCredential(req: IncomingMessage): boolean {
+  return req.headers['x-api-key'] !== undefined || req.headers.authorization !== undefined;
+}
+
+/** `true` when the request carries a credential matching `expected`. */
+export function isAuthorized(req: IncomingMessage, expected: string): boolean {
+  const presented = extractPresentedToken(req);
+  if (presented === null) return false;
+  return tokensMatch(presented, expected);
+}
+
+/**
+ * 401 with `WWW-Authenticate: Bearer`. The body deliberately says nothing
+ * about whether a credential was absent, malformed, or simply wrong.
+ */
+export function sendUnauthorized(res: ServerResponse): void {
+  res.writeHead(401, {
+    'WWW-Authenticate': 'Bearer realm="mlx-node"',
+    'Content-Type': 'application/json',
+  });
+  res.end(
+    JSON.stringify({
+      error: {
+        type: 'authentication_error',
+        message: 'Missing or invalid API key',
+        code: null,
+        param: null,
+      },
+    }),
+  );
+}

package/src/chat-session-warm-reuse.ts

@@ -0,0 +1,96 @@
+/**
+ * Server-private `ChatSession` warm-reuse helper.
+ *
+ * Kept out of the `@mlx-node/lm` package exports entirely so downstream
+ * consumers cannot reach it: the module lives inside
+ * `@mlx-node/server`, its file path is not on the server's export map,
+ * and nothing re-exports it. Callers are the two server endpoints —
+ * `endpoints/responses.ts` (tier-1 / tier-2 HIT branch) and
+ * `endpoints/messages.ts` (`getOrCreateWarmAny` HIT branch) — each
+ * invoking the helper only when native cache reuse is authorized: either a
+ * `SessionRegistry` hit or a block-paged model whose allocator validates
+ * reusable prefixes by content hash and isolates live cache owners.
+ *
+ * Why this helper exists at all: public `ChatSession.reset()` invalidates the
+ * current session's native state — owner-scoped on block-paged models and
+ * model-wide on exclusive/flat models. A warm registry HIT instead needs to
+ * preserve the already-authorized native prefix while clearing only the JS
+ * conversation wrapper. Warm leases provide the ownership gate; block-paged
+ * adapters provide the content-verification gate. A JS-state-only reset is
+ * valid in either case.
+ *
+ * Fields accessed: `inFlight`, `history`, `lastImagesKey`, `lastAudioKey`, `turnCount`,
+ * `unresolvedOkToolCallCount`, `needsFullReplay`, `defaultConfig`, `activeTools`.
+ * These are TypeScript `private` fields on `ChatSession` (compile-time
+ * only) — at runtime they are ordinary properties. The cast through
+ * {@link ChatSessionWarmReuseInternals} gives this helper a typed view
+ * of the instance without relaxing the class's `private` declarations.
+ * The field names MUST stay in sync with
+ * `packages/lm/src/chat-session.ts`; a mismatch would silently skip
+ * the intended state wipe and is covered by the warm-reuse unit tests.
+ */
+
+import type { ChatConfig, ChatSession, SessionCapableModel } from '@mlx-node/lm';
+
+/**
+ * Private structural view of the `ChatSession` JS-side state that the
+ * warm-reuse helper needs to wipe. Mirrors the internal state
+ * documented on `ChatSession` itself — field names are load-bearing:
+ * they must byte-match the concrete class's private fields or the
+ * cast-based mutation below silently no-ops.
+ */
+interface ChatSessionWarmReuseInternals {
+  inFlight: boolean;
+  history: unknown[];
+  lastImagesKey: string | null;
+  lastAudioKey: string | null;
+  turnCount: number;
+  unresolvedOkToolCallCount: number | null;
+  needsFullReplay: boolean;
+  defaultConfig?: ChatConfig;
+  activeTools: ChatConfig['tools'];
+}
+
+/**
+ * JS-state-only reset that DELIBERATELY preserves the underlying
+ * model's native KV cache and `cached_token_history`.
+ *
+ * @internal server-private — used only by `SessionRegistry` HIT
+ * branches in `endpoints/responses.ts` and `endpoints/messages.ts`.
+ * Never export from this package's `index.ts`.
+ *
+ * Wipes ONLY the JS-side session state (history array, image key, turn
+ * counter, tool-call fan-out guard). With this function, the JS session
+ * is fresh enough for `ChatSession.primeHistory()` (which requires
+ * `turnCount === 0`) while the native prefix verifier can still recover
+ * the reused prefix on the next `chatSessionStart` and skip the
+ * corresponding re-prefill.
+ */
+export async function resetPreservingNativeCacheForWarmReuse<M extends SessionCapableModel>(
+  session: ChatSession<M>,
+): Promise<void> {
+  // TypeScript `private` fields are only compile-time checks; at
+  // runtime they are ordinary properties. The cast through
+  // `ChatSessionWarmReuseInternals` preserves full static typing for
+  // this helper's mutations while bypassing the `private` gate — which
+  // is correct here because this helper is the designated server-side
+  // friend accessor. The cast is funneled through `unknown` because TS
+  // correctly rejects a direct `ChatSession → Internals` cast when the
+  // concrete class has other non-internals fields.
+  const internals = session as unknown as ChatSessionWarmReuseInternals;
+  if (internals.inFlight) {
+    throw new Error(
+      'ChatSession: cannot resetPreservingNativeCacheForWarmReuse() while a send() is in flight; await the previous call first',
+    );
+  }
+  internals.history = [];
+  internals.lastImagesKey = null;
+  internals.lastAudioKey = null;
+  internals.turnCount = 0;
+  internals.unresolvedOkToolCallCount = null;
+  internals.needsFullReplay = false;
+  // Tools are conversation state. A warm-any lease may belong to an
+  // unrelated request, so restore constructor defaults exactly like
+  // ChatSession.reset() instead of leaking the prior committed overlay.
+  internals.activeTools = internals.defaultConfig?.tools;
+}

package/src/endpoints/messages-count-tokens.ts

@@ -0,0 +1,164 @@
+/** POST /v1/messages/count_tokens — Anthropic Messages token-count endpoint. */
+
+import type { ServerResponse } from 'node:http';
+
+import type { ChatMessage, ToolDefinition } from '@mlx-node/core';
+
+import {
+  sendAnthropicBadRequest,
+  sendAnthropicInternalError,
+  sendAnthropicNotFound,
+  sendAnthropicNotImplemented,
+} from '../errors.js';
+import type { IdleSweeper } from '../idle-sweeper.js';
+import { mapAnthropicRequest } from '../mappers/anthropic-request.js';
+import type { ModelWorkCoordinator } from '../model-work-coordinator.js';
+import type { ModelRegistry, ServableModel } from '../registry.js';
+import type { AnthropicCountTokensRequest, AnthropicCountTokensResponse } from '../types-anthropic.js';
+
+interface ChatTemplateTokenCounter {
+  applyChatTemplate(
+    messages: ChatMessage[],
+    addGenerationPrompt?: boolean | null,
+    tools?: ToolDefinition[] | null,
+    enableThinking?: boolean | null,
+  ): Promise<Uint32Array> | Uint32Array;
+}
+
+function getChatTemplateTokenCounter(model: ServableModel): ChatTemplateTokenCounter | null {
+  const candidate = model as ServableModel & Partial<ChatTemplateTokenCounter>;
+  return typeof candidate.applyChatTemplate === 'function' ? (candidate as ChatTemplateTokenCounter) : null;
+}
+
+function endJson(res: ServerResponse, body: AnthropicCountTokensResponse): void {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+export async function handleCountMessageTokens(
+  res: ServerResponse,
+  body: AnthropicCountTokensRequest,
+  registry: ModelRegistry,
+  idleSweeper?: IdleSweeper | null,
+  resolveModel?: (name: string) => Promise<void>,
+  modelWorkCoordinator?: ModelWorkCoordinator,
+): Promise<void> {
+  if (body == null || typeof body !== 'object') {
+    sendAnthropicBadRequest(res, 'Request body must be a JSON object');
+    return;
+  }
+  if (!body.model) {
+    sendAnthropicBadRequest(res, 'Missing required field: model');
+    return;
+  }
+  if (!body.messages || !Array.isArray(body.messages) || body.messages.length === 0) {
+    sendAnthropicBadRequest(res, 'Missing required field: messages');
+    return;
+  }
+
+  for (const msg of body.messages) {
+    if (msg == null || typeof msg !== 'object') {
+      sendAnthropicBadRequest(res, 'Each message must be a non-null object');
+      return;
+    }
+  }
+
+  let mapped: ReturnType<typeof mapAnthropicRequest>;
+  try {
+    mapped = mapAnthropicRequest(body);
+  } catch (err) {
+    sendAnthropicBadRequest(res, err instanceof Error ? err.message : 'Invalid request');
+    return;
+  }
+
+  if (resolveModel) {
+    try {
+      const runResolve = () =>
+        idleSweeper ? idleSweeper.withSuspendedDrains(() => resolveModel(body.model)) : resolveModel(body.model);
+      if (modelWorkCoordinator) await modelWorkCoordinator.withModelLoad(runResolve);
+      else await runResolve();
+    } catch (err) {
+      sendAnthropicInternalError(res, err instanceof Error ? err.message : 'Failed to resolve model');
+      return;
+    }
+  }
+
+  const lease = registry.acquireDispatchLease(body.model);
+  if (!lease) {
+    if (registry.get(body.model) != null) {
+      sendAnthropicInternalError(res, 'session registry missing for registered model');
+      return;
+    }
+    sendAnthropicNotFound(res, `Model "${body.model}" not found`);
+    return;
+  }
+  const leaseModel = lease.model;
+  const sessionReg = lease.registry;
+  const preLockInstanceId = lease.instanceId;
+
+  try {
+    // Token counting is a pure-CPU tokenize-and-template operation; it must NOT
+    // queue behind the per-model generation FIFO (`sessionReg.withExclusive`)
+    // because that serializes against multi-minute decode passes and turns a
+    // millisecond call into a multi-hundred-second wait. The dispatch lease
+    // already pins the model object + binding for the duration of this call,
+    // and `withInference` (a shared reader lock against `withModelLoad`) is
+    // enough to keep the model from being swapped out mid-tokenize.
+    const bindingStillMatchesLease = () => {
+      const lockedSessionReg = registry.getSessionRegistry(body.model);
+      const lockedInstanceId = registry.getInstanceId(body.model);
+      return (
+        lockedSessionReg !== undefined &&
+        lockedInstanceId !== undefined &&
+        lockedSessionReg === sessionReg &&
+        lockedInstanceId === preLockInstanceId
+      );
+    };
+
+    const rejectChangedBinding = (phase: string) => {
+      sendAnthropicBadRequest(
+        res,
+        `Model "${body.model}" binding changed while the token-count request was ${phase}. ` +
+          `A concurrent register() re-pointed the name at a different model instance ` +
+          `(or released it entirely), so counting against the leased model would use ` +
+          `a stale model object. Retry the request — if the swap was intentional, the ` +
+          `new binding will service the retry cleanly.`,
+      );
+    };
+
+    const runCountWithModelRead = async () => {
+      if (!bindingStillMatchesLease()) {
+        rejectChangedBinding('waiting for the model-load reader gate');
+        return;
+      }
+
+      const counter = getChatTemplateTokenCounter(leaseModel);
+      if (!counter) {
+        sendAnthropicNotImplemented(
+          res,
+          `Model "${body.model}" does not expose applyChatTemplate(); token counting requires a ` +
+            `non-generating chat-template tokenizer API on the registered model.`,
+        );
+        return;
+      }
+
+      try {
+        const tokens = await counter.applyChatTemplate(mapped.messages, true, mapped.config.tools ?? null);
+        if (!bindingStillMatchesLease()) {
+          rejectChangedBinding('running');
+          return;
+        }
+        endJson(res, { input_tokens: tokens.length });
+      } catch (err) {
+        sendAnthropicInternalError(res, err instanceof Error ? err.message : 'Failed to count tokens');
+      }
+    };
+
+    if (modelWorkCoordinator) await modelWorkCoordinator.withInference(runCountWithModelRead);
+    else await runCountWithModelRead();
+  } catch (err) {
+    sendAnthropicInternalError(res, err instanceof Error ? err.message : 'Failed to count tokens');
+  } finally {
+    registry.releaseDispatchLease(leaseModel);
+  }
+}