@nemesis-oss/ollama-sdk 1.11.0 → 1.12.0

package/dist/index.js

@@ -1035,6 +1035,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}");
@@ -1572,6 +1593,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("[")) {
@@ -2184,151 +2455,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;
@@ -5315,7 +5441,7 @@ function createLogicalRequestId() {
   logicalRequestSequence += 1;
   return `ollama-request-${logicalRequestSequence}`;
 }
-var OllamaClient = class {
+var OllamaClient = class _OllamaClient {
   registry;
   models;
   retryConfig;
@@ -5347,6 +5473,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);
@@ -5374,6 +5510,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() {
@@ -5584,7 +5725,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,
@@ -6106,9 +6248,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
@@ -7469,6 +7716,6 @@ function estimateSystemOneRequestBytes(request) {
   return new TextEncoder().encode(JSON.stringify(request)).byteLength;
 }
 
-export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, ModelAffinityScheduler, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAgentToolLoopError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, addSpanEvent, applySkill, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, extractUsage, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, resolveImageInput, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
+export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, Agent, AnthropicCompatClient, AnthropicMessagesStream, ConversationSession, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, IMAGE_TOKEN_ESTIMATE, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, ModelAffinityRouter, ModelAffinityScheduler, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAgentMaxToolCallsError, OllamaAgentToolLoopError, OllamaAuthError, OllamaBadGatewayError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaIncompatibleModelError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaOverloadedError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaRequestTooLargeError, OllamaRequestValidationError, OllamaResponseValidationError, OllamaServerError, OllamaServerVersionUnknownError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaStreamError, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAIChatCompletionStream, OpenAICompatClient, OpenAICompletionStream, OpenAIResponsesStream, OpenAIResponsesStreamError, QuotaManager, RETRYABLE_STATUS_CODES, ResponsesModule, ToolCallAccumulator, ToolRegistry, addSpanEvent, applySkill, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, composeMiddleware, contextWarningMessage, createConsoleLogger, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, extractUsage, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, imageStringNeedsResolution, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mapError, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseSseStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, resolveImageInput, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map