@nemesis-oss/ollama-sdk 1.11.0 → 1.12.0

package/dist/index.cjs

@@ -1037,6 +1037,27 @@ var ATTR_OLLAMA_AGENT_MAX_ITERATIONS = "ollama.agent.max_iterations";
 var ATTR_OLLAMA_AGENT_ITERATION = "ollama.agent.iteration";
 var GEN_AI_SYSTEM_OLLAMA = "ollama";
 
+// src/telemetry/metrics.ts
+function nsToMs(ns) {
+  return ns ? Math.round(ns / 1e6 * 100) / 100 : 0;
+}
+function formatTelemetry(raw) {
+  const evalDurationSec = raw.eval_duration ? raw.eval_duration / 1e9 : 0;
+  const promptDurationSec = raw.prompt_eval_duration ? raw.prompt_eval_duration / 1e9 : 0;
+  const promptEvaluated = raw.prompt_eval_count ?? 0;
+  const promptCached = raw.prompt_eval_cached_count ?? 0;
+  const promptTotal = promptCached + promptEvaluated;
+  return {
+    totalLatencyMs: nsToMs(raw.total_duration),
+    modelLoadMs: nsToMs(raw.load_duration),
+    promptEvalMs: nsToMs(raw.prompt_eval_duration),
+    generationMs: nsToMs(raw.eval_duration),
+    tokensPerSecond: evalDurationSec > 0 && raw.eval_count ? Math.round(raw.eval_count / evalDurationSec * 10) / 10 : 0,
+    promptTokensPerSecond: promptDurationSec > 0 && promptEvaluated ? Math.round(promptEvaluated / promptDurationSec * 10) / 10 : 0,
+    cacheHitRatio: promptTotal > 0 ? Math.round(promptCached / promptTotal * 1e3) / 1e3 : 0
+  };
+}
+
 // src/transport/http.ts
 function routeTemplate(path) {
   return path.replace(/^\/api\/blobs\/.+$/, "/api/blobs/{digest}");
@@ -1574,6 +1595,256 @@ async function listAvailableModels(http) {
   });
   return [...res.models];
 }
+
+// src/context-safety.ts
+var DEFAULT_CONTEXT_WARNING_THRESHOLD = 0.9;
+var IMAGE_TOKEN_ESTIMATE = 300;
+var CHARS_PER_TOKEN = 4;
+function isCjkCodePoint(code) {
+  return code >= 19968 && code <= 40959 || // CJK Unified Ideographs
+  code >= 13312 && code <= 19903 || // CJK Extension A
+  code >= 12352 && code <= 12543 || // Hiragana + Katakana
+  code >= 44032 && code <= 55215 || // Hangul syllables
+  code >= 63744 && code <= 64255 || // CJK Compatibility Ideographs
+  code >= 65280 && code <= 65519;
+}
+function estimateTokens(text) {
+  if (text.length === 0) return 0;
+  let cjk = 0;
+  let other = 0;
+  for (const char of text) {
+    if (isCjkCodePoint(char.codePointAt(0) ?? 0)) cjk += 1;
+    else other += 1;
+  }
+  return Math.ceil(cjk + other / CHARS_PER_TOKEN);
+}
+var MESSAGE_OVERHEAD_TOKENS = 4;
+function estimateMessageTokens(message) {
+  let total = MESSAGE_OVERHEAD_TOKENS + estimateTokens(message.content ?? "");
+  if (message.thinking !== void 0) total += estimateTokens(message.thinking);
+  if (message.tool_calls !== void 0) {
+    for (const call of message.tool_calls) {
+      total += estimateTokens(call.function.name);
+      total += estimateTokens(JSON.stringify(call.function.arguments ?? {}));
+    }
+  }
+  if (message.images !== void 0) total += message.images.length * IMAGE_TOKEN_ESTIMATE;
+  return total;
+}
+function estimateChatRequestTokens(req) {
+  let total = 0;
+  for (const message of req.messages) total += estimateMessageTokens(message);
+  if (req.tools !== void 0) {
+    for (const tool of req.tools) {
+      total += estimateTokens(tool.function.description ?? "");
+      total += estimateTokens(JSON.stringify(tool.function.parameters ?? {}));
+    }
+  }
+  return total;
+}
+function estimateGenerateRequestTokens(req) {
+  let total = estimateTokens(req.prompt ?? "");
+  if (req.system !== void 0) total += estimateTokens(req.system);
+  if (req.template !== void 0) total += estimateTokens(req.template);
+  if (req.images !== void 0) total += req.images.length * IMAGE_TOKEN_ESTIMATE;
+  return total;
+}
+function checkChatContext(req, options = {}) {
+  return check(estimateChatRequestTokens(req), req.options?.num_ctx, options);
+}
+function checkGenerateContext(req, options = {}) {
+  return check(estimateGenerateRequestTokens(req), req.options?.num_ctx, options);
+}
+function check(estimatedPromptTokens, requestNumCtx, options) {
+  const threshold = options.threshold ?? DEFAULT_CONTEXT_WARNING_THRESHOLD;
+  if (requestNumCtx !== void 0) {
+    return {
+      estimatedPromptTokens,
+      effectiveContextLength: requestNumCtx,
+      windowSource: "request",
+      exceedsThreshold: estimatedPromptTokens > requestNumCtx * threshold
+    };
+  }
+  if (options.defaultContextLength !== void 0) {
+    return {
+      estimatedPromptTokens,
+      effectiveContextLength: options.defaultContextLength,
+      windowSource: "client-default",
+      exceedsThreshold: estimatedPromptTokens > options.defaultContextLength * threshold
+    };
+  }
+  return {
+    estimatedPromptTokens,
+    effectiveContextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH,
+    windowSource: "server-fallback",
+    exceedsThreshold: estimatedPromptTokens > OLLAMA_FALLBACK_CONTEXT_LENGTH
+  };
+}
+var OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
+function contextWarningMessage(check2, kind) {
+  const where = `OllamaClient.${kind}()`;
+  const estimate = `~${check2.estimatedPromptTokens} tokens`;
+  if (check2.windowSource === "request") {
+    return `${where}: estimated prompt size ${estimate} is close to or beyond the request's context window (num_ctx=${check2.effectiveContextLength}). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`options.num_ctx\` or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+  }
+  if (check2.windowSource === "client-default") {
+    return `${where}: estimated prompt size ${estimate} is close to or beyond the client's \`defaultContextLength\` (${check2.effectiveContextLength}, injected as \`num_ctx\`). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`defaultContextLength\`, set \`options.num_ctx\` per request, or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+  }
+  return `${where}: estimated prompt size ${estimate} outright exceeds Ollama's conservative server-default context window (${OLLAMA_FALLBACK_CONTEXT_LENGTH}\u20134096 tokens when \`num_ctx\` is unset \u2014 model-dependent). Unless the model's default is larger, the server will silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Set \`options.num_ctx\` (or the client's \`defaultContextLength\`) to an explicit window to make truncation visible and controllable. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+}
+
+// src/context-discovery.ts
+function extractParameterNumCtx(parameters) {
+  if (!parameters) return void 0;
+  const match = /^[ \t]*num_ctx[ \t]+(\d+)\s*$/m.exec(parameters);
+  if (match === null) return void 0;
+  const value = Number.parseInt(match[1], 10);
+  return Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function matchesModelReference(entry, model) {
+  const exact = entry.name === model || entry.model === model;
+  const taglessPrefix = !model.includes(":") && (entry.name !== void 0 && entry.name.startsWith(`${model}:`) || entry.model !== void 0 && entry.model.startsWith(`${model}:`));
+  return exact || taglessPrefix;
+}
+function isModelResident(psModels, model) {
+  return psModels.some((entry) => matchesModelReference(entry, model));
+}
+function findRunningModelContextLength(psModels, model) {
+  for (const entry of psModels) {
+    if (matchesModelReference(entry, model)) {
+      return typeof entry.context_length === "number" && Number.isFinite(entry.context_length) && entry.context_length > 0 ? entry.context_length : void 0;
+    }
+  }
+  return void 0;
+}
+function positiveInt(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function resolveContextLength(signals) {
+  const running = positiveInt(signals.running);
+  const parameter = positiveInt(signals.parameter);
+  const native = positiveInt(signals.native);
+  if (running !== void 0) {
+    return {
+      contextLength: running,
+      source: "running",
+      ...parameter !== void 0 ? { parameterContextLength: parameter } : {},
+      ...native !== void 0 ? { nativeContextLength: native } : {},
+      runningContextLength: running
+    };
+  }
+  if (parameter !== void 0) {
+    return {
+      contextLength: parameter,
+      source: "parameters",
+      parameterContextLength: parameter,
+      ...native !== void 0 ? { nativeContextLength: native } : {}
+    };
+  }
+  if (native !== void 0) {
+    return { contextLength: native, source: "model-info", nativeContextLength: native };
+  }
+  return { contextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH, source: "fallback" };
+}
+
+// src/providers/model-affinity-router.ts
+var DEFAULT_TTL_MS = 3e4;
+var DEFAULT_FAILURE_RETRY_MS = 5e3;
+var ModelAffinityRouter = class {
+  fetchPs;
+  ttlMs;
+  failureRetryMs;
+  now;
+  cache = /* @__PURE__ */ new Map();
+  failedAt = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Map();
+  constructor(fetchPs, options = {}) {
+    this.fetchPs = fetchPs;
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.failureRetryMs = options.failureRetryMs ?? DEFAULT_FAILURE_RETRY_MS;
+    this.now = options.now ?? Date.now;
+  }
+  /**
+   * Synchronously reorders `candidates` so endpoints whose fresh `/api/ps`
+   * snapshot shows `model` resident come first (relative order preserved within
+   * each group). Returns the input unchanged — and kicks a background refresh —
+   * when any candidate's snapshot is missing or stale: a wrong reorder is worse
+   * than no reorder, and the first request after a cache miss simply isn't
+   * reordered. No-op without a `model` or with fewer than two candidates.
+   */
+  reorder(candidates, model) {
+    if (model === void 0 || candidates.length < 2) return candidates;
+    const currentTime = this.now();
+    let allFresh = true;
+    for (const endpoint of candidates) {
+      const entry = this.cache.get(endpoint.name);
+      if (entry === void 0 || currentTime - entry.fetchedAt > this.ttlMs) {
+        allFresh = false;
+        this.kickRefresh(endpoint);
+      }
+    }
+    if (!allFresh) return candidates;
+    const resident = candidates.filter((ep) => {
+      const entry = this.cache.get(ep.name);
+      return entry !== void 0 && isModelResident(entry.models, model);
+    });
+    if (resident.length === 0 || resident.length === candidates.length) return candidates;
+    const residentSet = new Set(resident.map((ep) => ep.name));
+    return [...resident, ...candidates.filter((ep) => !residentSet.has(ep.name))];
+  }
+  /**
+   * Forces a refresh of the affinity cache for the given endpoints (deduped with
+   * any in-flight refresh; bypasses the failure backoff, because this is an
+   * explicit caller request — `client.warmModelAffinity()`). Resolves once every
+   * probe has settled — successfully or not; individual failures never reject.
+   */
+  async warm(endpoints) {
+    await Promise.all(endpoints.map((endpoint) => this.refresh(endpoint)));
+  }
+  /** Introspection snapshots for the given endpoints (defaults to cached ones). */
+  status(endpoints) {
+    const names = endpoints !== void 0 ? endpoints.map((ep) => ep.name) : [...this.cache.keys(), ...this.failedAt.keys()];
+    const byName = new Map((endpoints ?? []).map((ep) => [ep.name, ep]));
+    const currentTime = this.now();
+    return names.filter((name, i, arr) => arr.indexOf(name) === i).map((name) => {
+      const entry = this.cache.get(name);
+      return {
+        endpointName: name,
+        baseUrl: byName.get(name)?.baseUrl ?? "",
+        loadedModels: entry?.models.map((m) => m.name ?? m.model ?? "").filter((n) => n !== "") ?? [],
+        fetchedAt: entry?.fetchedAt,
+        fresh: entry !== void 0 && currentTime - entry.fetchedAt <= this.ttlMs
+      };
+    });
+  }
+  /**
+   * Starts (or joins) a background refresh for `endpoint`, unless one is already
+   * in flight or the failure backoff suppresses it. Fire-and-forget: the promise
+   * is stored only for dedupe/warm-joins; callers never await it on the request
+   * path.
+   */
+  kickRefresh(endpoint) {
+    if (this.inflight.has(endpoint.name)) return;
+    const lastFailure = this.failedAt.get(endpoint.name);
+    if (lastFailure !== void 0 && this.now() - lastFailure < this.failureRetryMs) return;
+    void this.refresh(endpoint);
+  }
+  /** Refreshes one endpoint's snapshot; never rejects (failures record a backoff). */
+  refresh(endpoint) {
+    const existing = this.inflight.get(endpoint.name);
+    if (existing !== void 0) return existing;
+    const attempt = this.fetchPs(endpoint).then((models) => {
+      this.cache.set(endpoint.name, { models, fetchedAt: this.now() });
+      this.failedAt.delete(endpoint.name);
+    }).catch(() => {
+      this.failedAt.set(endpoint.name, this.now());
+    }).finally(() => {
+      this.inflight.delete(endpoint.name);
+    });
+    this.inflight.set(endpoint.name, attempt);
+    return attempt;
+  }
+};
 function extractJsonSubstring(text) {
   const trimmed = text.trim();
   if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
@@ -2186,151 +2457,6 @@ function createTimeoutSignal(timeoutMs, userSignal) {
   return { signal: controller.signal, cancel };
 }
 
-// src/context-safety.ts
-var DEFAULT_CONTEXT_WARNING_THRESHOLD = 0.9;
-var IMAGE_TOKEN_ESTIMATE = 300;
-var CHARS_PER_TOKEN = 4;
-function isCjkCodePoint(code) {
-  return code >= 19968 && code <= 40959 || // CJK Unified Ideographs
-  code >= 13312 && code <= 19903 || // CJK Extension A
-  code >= 12352 && code <= 12543 || // Hiragana + Katakana
-  code >= 44032 && code <= 55215 || // Hangul syllables
-  code >= 63744 && code <= 64255 || // CJK Compatibility Ideographs
-  code >= 65280 && code <= 65519;
-}
-function estimateTokens(text) {
-  if (text.length === 0) return 0;
-  let cjk = 0;
-  let other = 0;
-  for (const char of text) {
-    if (isCjkCodePoint(char.codePointAt(0) ?? 0)) cjk += 1;
-    else other += 1;
-  }
-  return Math.ceil(cjk + other / CHARS_PER_TOKEN);
-}
-var MESSAGE_OVERHEAD_TOKENS = 4;
-function estimateMessageTokens(message) {
-  let total = MESSAGE_OVERHEAD_TOKENS + estimateTokens(message.content ?? "");
-  if (message.thinking !== void 0) total += estimateTokens(message.thinking);
-  if (message.tool_calls !== void 0) {
-    for (const call of message.tool_calls) {
-      total += estimateTokens(call.function.name);
-      total += estimateTokens(JSON.stringify(call.function.arguments ?? {}));
-    }
-  }
-  if (message.images !== void 0) total += message.images.length * IMAGE_TOKEN_ESTIMATE;
-  return total;
-}
-function estimateChatRequestTokens(req) {
-  let total = 0;
-  for (const message of req.messages) total += estimateMessageTokens(message);
-  if (req.tools !== void 0) {
-    for (const tool of req.tools) {
-      total += estimateTokens(tool.function.description ?? "");
-      total += estimateTokens(JSON.stringify(tool.function.parameters ?? {}));
-    }
-  }
-  return total;
-}
-function estimateGenerateRequestTokens(req) {
-  let total = estimateTokens(req.prompt ?? "");
-  if (req.system !== void 0) total += estimateTokens(req.system);
-  if (req.template !== void 0) total += estimateTokens(req.template);
-  if (req.images !== void 0) total += req.images.length * IMAGE_TOKEN_ESTIMATE;
-  return total;
-}
-function checkChatContext(req, options = {}) {
-  return check(estimateChatRequestTokens(req), req.options?.num_ctx, options);
-}
-function checkGenerateContext(req, options = {}) {
-  return check(estimateGenerateRequestTokens(req), req.options?.num_ctx, options);
-}
-function check(estimatedPromptTokens, requestNumCtx, options) {
-  const threshold = options.threshold ?? DEFAULT_CONTEXT_WARNING_THRESHOLD;
-  if (requestNumCtx !== void 0) {
-    return {
-      estimatedPromptTokens,
-      effectiveContextLength: requestNumCtx,
-      windowSource: "request",
-      exceedsThreshold: estimatedPromptTokens > requestNumCtx * threshold
-    };
-  }
-  if (options.defaultContextLength !== void 0) {
-    return {
-      estimatedPromptTokens,
-      effectiveContextLength: options.defaultContextLength,
-      windowSource: "client-default",
-      exceedsThreshold: estimatedPromptTokens > options.defaultContextLength * threshold
-    };
-  }
-  return {
-    estimatedPromptTokens,
-    effectiveContextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH,
-    windowSource: "server-fallback",
-    exceedsThreshold: estimatedPromptTokens > OLLAMA_FALLBACK_CONTEXT_LENGTH
-  };
-}
-var OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
-function contextWarningMessage(check2, kind) {
-  const where = `OllamaClient.${kind}()`;
-  const estimate = `~${check2.estimatedPromptTokens} tokens`;
-  if (check2.windowSource === "request") {
-    return `${where}: estimated prompt size ${estimate} is close to or beyond the request's context window (num_ctx=${check2.effectiveContextLength}). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`options.num_ctx\` or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
-  }
-  if (check2.windowSource === "client-default") {
-    return `${where}: estimated prompt size ${estimate} is close to or beyond the client's \`defaultContextLength\` (${check2.effectiveContextLength}, injected as \`num_ctx\`). The server will likely silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Raise \`defaultContextLength\`, set \`options.num_ctx\` per request, or shorten the conversation. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
-  }
-  return `${where}: estimated prompt size ${estimate} outright exceeds Ollama's conservative server-default context window (${OLLAMA_FALLBACK_CONTEXT_LENGTH}\u20134096 tokens when \`num_ctx\` is unset \u2014 model-dependent). Unless the model's default is larger, the server will silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Set \`options.num_ctx\` (or the client's \`defaultContextLength\`) to an explicit window to make truncation visible and controllable. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
-}
-
-// src/context-discovery.ts
-function extractParameterNumCtx(parameters) {
-  if (!parameters) return void 0;
-  const match = /^[ \t]*num_ctx[ \t]+(\d+)\s*$/m.exec(parameters);
-  if (match === null) return void 0;
-  const value = Number.parseInt(match[1], 10);
-  return Number.isFinite(value) && value > 0 ? value : void 0;
-}
-function findRunningModelContextLength(psModels, model) {
-  for (const entry of psModels) {
-    const exact = entry.name === model || entry.model === model;
-    const taglessPrefix = !model.includes(":") && (entry.name.startsWith(`${model}:`) || entry.model.startsWith(`${model}:`));
-    if (exact || taglessPrefix) {
-      return typeof entry.context_length === "number" && Number.isFinite(entry.context_length) && entry.context_length > 0 ? entry.context_length : void 0;
-    }
-  }
-  return void 0;
-}
-function positiveInt(value) {
-  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
-}
-function resolveContextLength(signals) {
-  const running = positiveInt(signals.running);
-  const parameter = positiveInt(signals.parameter);
-  const native = positiveInt(signals.native);
-  if (running !== void 0) {
-    return {
-      contextLength: running,
-      source: "running",
-      ...parameter !== void 0 ? { parameterContextLength: parameter } : {},
-      ...native !== void 0 ? { nativeContextLength: native } : {},
-      runningContextLength: running
-    };
-  }
-  if (parameter !== void 0) {
-    return {
-      contextLength: parameter,
-      source: "parameters",
-      parameterContextLength: parameter,
-      ...native !== void 0 ? { nativeContextLength: native } : {}
-    };
-  }
-  if (native !== void 0) {
-    return { contextLength: native, source: "model-info", nativeContextLength: native };
-  }
-  return { contextLength: OLLAMA_FALLBACK_CONTEXT_LENGTH, source: "fallback" };
-}
-
 // src/keep-alive.ts
 var KEEP_ALIVE_UNLOAD = 0;
 var KEEP_ALIVE_INDEFINITE = -1;
@@ -5317,7 +5443,7 @@ function createLogicalRequestId() {
   logicalRequestSequence += 1;
   return `ollama-request-${logicalRequestSequence}`;
 }
-var OllamaClient = class {
+var OllamaClient = class _OllamaClient {
   registry;
   models;
   retryConfig;
@@ -5349,6 +5475,16 @@ var OllamaClient = class {
    * (streams, via `executeWithFailover`'s `holdUntil` release path).
    */
   activeRequests = /* @__PURE__ */ new Set();
+  /**
+   * Dynamic multi-host model-affinity routing, active only when
+   * `config.endpointHealth.modelAffinity` is set — see
+   * `src/providers/model-affinity-router.ts` and ADR 0028. `undefined` means
+   * the request path skips reordering entirely (zero overhead, and no `/api/ps`
+   * probes are ever issued).
+   */
+  modelAffinity;
+  /** Default timeout for one-off probe requests (`ping`, affinity `/api/ps` refreshes). */
+  static PROBE_TIMEOUT_MS = 5e3;
   constructor(config = {}) {
     this.cloudApiKey = resolveApiKey(config.apiKey);
     const defaultBaseUrl = resolveBaseUrl(config.baseUrl);
@@ -5376,6 +5512,11 @@ var OllamaClient = class {
     this.defaultContextLength = config.defaultContextLength;
     this.contextWarningThreshold = config.contextWarningThreshold;
     this.onContextOverflow = config.onContextOverflow ?? "warn";
+    const modelAffinityOptions = config.endpointHealth?.modelAffinity;
+    this.modelAffinity = modelAffinityOptions !== void 0 ? new ModelAffinityRouter(
+      (endpoint) => this.fetchEndpointRunningModels(endpoint),
+      modelAffinityOptions
+    ) : void 0;
     this.models = new ModelsClient((op, opts) => this.executeWithFailover(op, opts));
   }
   get modelsClient() {
@@ -5586,7 +5727,8 @@ var OllamaClient = class {
           );
           continue;
         }
-        for (const [attemptIndex, endpoint] of runnable.entries()) {
+        const ordered = this.modelAffinity !== void 0 ? this.modelAffinity.reorder(runnable, options?.model) : runnable;
+        for (const [attemptIndex, endpoint] of ordered.entries()) {
           this.logger.debug(`Executing on endpoint "${endpoint.name}" (${endpoint.baseUrl})`);
           const http = new HttpClient({
             baseUrl: endpoint.baseUrl,
@@ -6108,9 +6250,114 @@ var OllamaClient = class {
       )
     );
   }
+  /**
+   * Ultra-lightweight liveness probe against the client's current best
+   * endpoint: `HEAD /` — the root ping Ollama's documentation defines for
+   * load-balancer health checks (HTTP 200; the daemon answers `GET /` with the
+   * plain-text body "Ollama is running", which a HEAD request doesn't transfer).
+   *
+   * Deliberately a *single-endpoint, single-shot* probe — no failover to other
+   * candidates, no retry — so the answer reflects one concrete host, not "some
+   * endpoint eventually answered". To audit every configured endpoint, use
+   * {@link healthCheck} (which probes all of them, and also reports the server
+   * version at the cost of the heavier `GET /api/version` round trip).
+   *
+   * Resolves — never throws — with `{ healthy: false, error }` for connection
+   * failures and timeouts; only caller-initiated cancellation (`signal`/
+   * `destroy()`) rejects, mirroring how any other aborted request behaves.
+   */
+  async ping(options) {
+    const endpoint = this.registry.candidates()[0];
+    if (endpoint === void 0) {
+      return { healthy: false, latencyMs: 0, baseUrl: "", error: "No configured endpoints" };
+    }
+    const http = new HttpClient({
+      baseUrl: endpoint.baseUrl,
+      ...endpoint.apiKey !== void 0 ? { apiKey: endpoint.apiKey } : {},
+      ...endpoint.headers !== void 0 ? { headers: endpoint.headers } : {},
+      fetch: this.fetchImpl,
+      middleware: this.middleware,
+      onLifecycleEvent: this.onLifecycleEvent
+    });
+    const timeout = createTimeoutSignal(
+      options?.timeoutMs ?? _OllamaClient.PROBE_TIMEOUT_MS,
+      options?.signal
+    );
+    const startTime = Date.now();
+    try {
+      await http.request({ path: "/", method: "HEAD", signal: timeout.signal });
+      return { healthy: true, latencyMs: Date.now() - startTime, baseUrl: endpoint.baseUrl };
+    } catch (err) {
+      if (options?.signal?.aborted) {
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+      return {
+        healthy: false,
+        latencyMs: Date.now() - startTime,
+        baseUrl: endpoint.baseUrl,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    } finally {
+      timeout.cancel();
+    }
+  }
+  /**
+   * Affinity-cache snapshots for every configured endpoint — which models each
+   * host held in VRAM at the last successful `/api/ps` probe, when that was, and
+   * whether it's still fresh. Empty when `endpointHealth.modelAffinity` isn't
+   * configured (no probes are ever issued, so there is nothing to report).
+   */
+  modelAffinityStatus() {
+    return this.modelAffinity?.status(this.registry.list()) ?? [];
+  }
+  /**
+   * Explicitly refreshes the model-affinity cache for every configured endpoint
+   * (deduped with any in-flight background refresh). No-op — resolves
+   * immediately — when `endpointHealth.modelAffinity` isn't configured. Use it
+   * to warm the cache at startup so the very first request already routes by
+   * residency instead of waiting for the self-warming first-round refresh.
+   */
+  async warmModelAffinity() {
+    await this.modelAffinity?.warm(this.registry.list());
+  }
   endpointStatus() {
     return this.registry.status();
   }
+  /**
+   * Fetches one endpoint's `GET /api/ps` running-model list for the affinity
+   * router. Bypasses `executeWithFailover` deliberately: probes must not
+   * reenter the routing machinery they inform, must not touch the registry's
+   * circuit-breaker/failure bookkeeping (a dead host's probe failing must not
+   * cool it down harder than its real traffic already does), and must not fail
+   * over to a different host (the answer is per-host by definition). Failures
+   * propagate to the router, which records a short backoff and retries later.
+   */
+  async fetchEndpointRunningModels(endpoint) {
+    var _stack = [];
+    try {
+      const http = new HttpClient({
+        baseUrl: endpoint.baseUrl,
+        ...endpoint.apiKey !== void 0 ? { apiKey: endpoint.apiKey } : {},
+        ...endpoint.headers !== void 0 ? { headers: endpoint.headers } : {},
+        fetch: this.fetchImpl,
+        middleware: this.middleware,
+        onLifecycleEvent: this.onLifecycleEvent
+      });
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), _OllamaClient.PROBE_TIMEOUT_MS);
+      const _timer = __using(_stack, disposableTimer(timer));
+      const res = await http.request({
+        path: "/api/ps",
+        method: "GET",
+        signal: controller.signal
+      });
+      return res.models ?? [];
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      __callDispose(_stack, _error, _hasError);
+    }
+  }
   /**
    * Immediately aborts every in-flight request and active stream managed by
    * this client — the clean teardown path for short-lived processes, CLI
@@ -7512,6 +7759,7 @@ exports.MAX_SYSTEM_ONE_IMAGES_BYTES = MAX_SYSTEM_ONE_IMAGES_BYTES;
 exports.MAX_SYSTEM_ONE_REQUEST_BYTES = MAX_SYSTEM_ONE_REQUEST_BYTES;
 exports.MESSAGE_OVERHEAD_TOKENS = MESSAGE_OVERHEAD_TOKENS;
 exports.McpBridge = McpBridge;
+exports.ModelAffinityRouter = ModelAffinityRouter;
 exports.ModelAffinityScheduler = ModelAffinityScheduler;
 exports.ModelsClient = ModelsClient;
 exports.NANOS_PER_MS = NANOS_PER_MS;
@@ -7590,10 +7838,12 @@ exports.extractUsage = extractUsage;
 exports.fetchWithBackoff = fetchWithBackoff;
 exports.findOversizedEmbedInputs = findOversizedEmbedInputs;
 exports.findRunningModelContextLength = findRunningModelContextLength;
+exports.formatTelemetry = formatTelemetry;
 exports.imageStringNeedsResolution = imageStringNeedsResolution;
 exports.inferRuntimeMode = inferRuntimeMode;
 exports.isKeepAliveSugar = isKeepAliveSugar;
 exports.isKnownDoneReason = isKnownDoneReason;
+exports.isModelResident = isModelResident;
 exports.isSameToolCall = isSameToolCall;
 exports.listAllMcpTools = listAllMcpTools;
 exports.listAvailableModels = listAvailableModels;