@nemesis-oss/ollama-sdk 1.0.0 → 1.3.0

package/dist/index.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 // src/config.ts
 var DEFAULT_BASE_URL = "http://localhost:11434";
 var DEFAULT_TIMEOUT_MS = 3e4;
+var OLLAMA_CLOUD_BASE_URL = "https://ollama.com";
 function readEnv(name) {
   return typeof process !== "undefined" && process.env ? process.env[name] : void 0;
 }
@@ -12,6 +13,34 @@ function resolveBaseUrl(configBaseUrl) {
 function resolveApiKey(configApiKey) {
   return configApiKey ?? readEnv("OLLAMA_API_KEY");
 }
+function resolveCredentialEndpoints(config) {
+  if (config.credentials === void 0) return [];
+  const modelsByCredential = /* @__PURE__ */ new Map();
+  for (const [model, bound] of Object.entries(config.modelBindings ?? {})) {
+    for (const id of typeof bound === "string" ? [bound] : bound) {
+      if (!(id in config.credentials)) {
+        throw new Error(
+          `modelBindings["${model}"] references unknown credential "${id}" \u2014 it isn't in \`credentials\`. Known credentials: ${Object.keys(config.credentials).join(", ") || "(none)"}.`
+        );
+      }
+      const list = modelsByCredential.get(id) ?? [];
+      list.push(model);
+      modelsByCredential.set(id, list);
+    }
+  }
+  return Object.entries(config.credentials).map(([id, credential]) => {
+    const isDefault = id === config.defaultCredential;
+    const boundModels = isDefault ? void 0 : modelsByCredential.get(id);
+    return {
+      name: `credential:${id}`,
+      baseUrl: resolveBaseUrl(credential.baseUrl ?? config.baseUrl),
+      apiKey: credential.apiKey,
+      ...credential.headers !== void 0 ? { headers: credential.headers } : {},
+      ...boundModels !== void 0 ? { models: boundModels } : {},
+      priority: isDefault ? -1 : 0
+    };
+  });
+}
 var DEFAULT_FAILOVER_CODES = [
   "network_error",
   "timeout",
@@ -70,6 +99,15 @@ var OllamaRateLimitError = class extends OllamaClientError {
     this.retryAfterMs = options?.retryAfterMs;
   }
 };
+var OllamaQuotaExceededError = class extends OllamaClientError {
+  windowId;
+  resetAt;
+  constructor(message, options) {
+    super(message, { ...options, code: "quota_exceeded", retryable: false });
+    this.windowId = options.windowId;
+    this.resetAt = options.resetAt;
+  }
+};
 var OllamaServerError = class extends OllamaClientError {
   constructor(message, options) {
     super(message, { ...options, code: "server_error", retryable: true });
@@ -105,6 +143,15 @@ var OllamaUnsupportedCapabilityError = class extends OllamaClientError {
     this.capability = options.capability;
   }
 };
+var OllamaModelRoutingError = class extends OllamaClientError {
+  model;
+  availableModels;
+  constructor(message, options) {
+    super(message, { ...options, code: "model_routing_error", retryable: false });
+    this.model = options.model;
+    this.availableModels = options.availableModels;
+  }
+};
 var OllamaAgentMaxIterationsError = class extends OllamaClientError {
   maxIterations;
   constructor(message, options) {
@@ -216,17 +263,143 @@ var EndpointRegistry = class {
   failureThreshold;
   cooldownMs;
   now;
+  strategy;
+  roundRobinCounter = 0;
+  activeCounts = /* @__PURE__ */ new Map();
+  maxConcurrentPerEndpoint;
+  waiters = [];
   constructor(endpoints, options = {}) {
     this.endpoints = endpoints.length > 0 ? endpoints : [{ name: "default", baseUrl: "http://localhost:11434" }];
     this.failureThreshold = options.failureThreshold ?? 3;
     this.cooldownMs = options.cooldownMs ?? 3e4;
     this.now = options.now ?? Date.now;
+    this.strategy = options.strategy ?? "priority";
+    this.maxConcurrentPerEndpoint = options.maxConcurrentPerEndpoint;
+  }
+  /**
+   * Marks one more request as in-flight against `name`. Callers (`OllamaClient`) must
+   * pair every `acquire` with a `release` once that attempt finishes, success or not —
+   * see `OllamaClient.executeWithFailover`. Only affects candidate ordering when
+   * `strategy` is `'least-connections'`; harmless (just bookkeeping) otherwise, and
+   * always reflected in `status()`'s `activeRequests`.
+   */
+  acquire(name) {
+    this.activeCounts.set(name, (this.activeCounts.get(name) ?? 0) + 1);
+  }
+  /** Releases one in-flight request marked via `acquire`, waking one waiter for `name` if any. */
+  release(name) {
+    const next = (this.activeCounts.get(name) ?? 0) - 1;
+    if (next <= 0) {
+      this.activeCounts.delete(name);
+    } else {
+      this.activeCounts.set(name, next);
+    }
+    const idx = this.waiters.findIndex((w) => w.names.includes(name));
+    if (idx !== -1) {
+      const [waiter] = this.waiters.splice(idx, 1);
+      waiter?.cleanup();
+      waiter?.resolve();
+    }
+  }
+  /**
+   * `candidates` filtered down to those currently under `maxConcurrentPerEndpoint` (all
+   * of them, unchanged, if that option is unset).
+   */
+  filterWithCapacity(candidates) {
+    const cap = this.maxConcurrentPerEndpoint;
+    if (cap === void 0) return [...candidates];
+    return candidates.filter((ep) => (this.activeCounts.get(ep.name) ?? 0) < cap);
+  }
+  /**
+   * Resolves once any endpoint named in `names` has spare capacity under
+   * `maxConcurrentPerEndpoint` (a no-op resolve if that option is unset, or if one
+   * already does). Otherwise queues (FIFO per name) until a matching `release()` frees a
+   * slot, or rejects if `signal` aborts first — mirroring whatever aborted it
+   * (`OllamaTimeoutError`/the caller's own abort reason) so callers see the same error
+   * shape as any other in-flight request that times out or is cancelled. FIFO order is
+   * best-effort (a newly-arriving request can still win a race for a slot that just
+   * freed) — the capacity cap itself, not fairness, is the guarantee this exists for.
+   */
+  waitForCapacity(names, signal) {
+    const cap = this.maxConcurrentPerEndpoint;
+    if (cap === void 0) return Promise.resolve();
+    if (names.some((n) => (this.activeCounts.get(n) ?? 0) < cap)) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter = { names, resolve, cleanup: () => void 0 };
+      const onAbort = () => {
+        const idx = this.waiters.indexOf(waiter);
+        if (idx !== -1) this.waiters.splice(idx, 1);
+        reject(
+          signal?.reason instanceof Error ? signal.reason : new OllamaAbortError("Aborted while waiting for endpoint capacity")
+        );
+      };
+      if (signal !== void 0) {
+        if (signal.aborted) {
+          onAbort();
+          return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        waiter.cleanup = () => signal.removeEventListener("abort", onAbort);
+      }
+      this.waiters.push(waiter);
+    });
+  }
+  /**
+   * Rotates each same-`priority` group in `sorted` (already sorted highest-priority-first)
+   * by one position further per call, wrapping around within the group. Priority tiers
+   * themselves are never reordered — only candidates that were already tied.
+   */
+  applyRoundRobin(sorted) {
+    const offset = this.roundRobinCounter++;
+    const result = [];
+    let i = 0;
+    while (i < sorted.length) {
+      const priority = sorted[i]?.priority ?? 0;
+      let j = i + 1;
+      while (j < sorted.length && (sorted[j]?.priority ?? 0) === priority) j++;
+      const tier = sorted.slice(i, j);
+      const rotation = offset % tier.length;
+      result.push(...tier.slice(rotation), ...tier.slice(0, rotation));
+      i = j;
+    }
+    return result;
+  }
+  /**
+   * Reorders each same-`priority` group in `sorted` by ascending in-flight request count
+   * (from `acquire`/`release`); a stable sort, so candidates tied on active count keep
+   * their relative (priority-then-registration) order. Priority tiers themselves are
+   * never reordered.
+   */
+  applyLeastConnections(sorted) {
+    const result = [];
+    let i = 0;
+    while (i < sorted.length) {
+      const priority = sorted[i]?.priority ?? 0;
+      let j = i + 1;
+      while (j < sorted.length && (sorted[j]?.priority ?? 0) === priority) j++;
+      const tier = [...sorted.slice(i, j)].sort(
+        (a, b) => (this.activeCounts.get(a.name) ?? 0) - (this.activeCounts.get(b.name) ?? 0)
+      );
+      result.push(...tier);
+      i = j;
+    }
+    return result;
   }
-  candidates() {
+  /**
+   * Endpoints eligible for `model`, sorted healthy-first-by-priority (falling back to
+   * soonest-to-recover if every eligible endpoint is cooling down); same-priority
+   * candidates are further reordered per `options.strategy` (see
+   * `EndpointRegistryOptions.strategy`). When `model` is given, endpoints whose `models`
+   * allow-list doesn't include it are excluded entirely — see `OllamaEndpoint.models`.
+   * Omit `model` to consider every configured endpoint, regardless of any `models`
+   * restriction (used for non-model-scoped operations).
+   */
+  candidates(model) {
     const currentTime = this.now();
+    const scoped = model === void 0 ? this.endpoints : this.endpoints.filter((ep) => ep.models === void 0 || ep.models.includes(model));
     const healthy = [];
     const coolingDown = [];
-    for (const ep of this.endpoints) {
+    for (const ep of scoped) {
       const failures = this.failureCounts.get(ep.name) ?? 0;
       const lastFail = this.lastFailures.get(ep.name) ?? 0;
       const isCooling = failures >= this.failureThreshold && currentTime - lastFail < this.cooldownMs;
@@ -237,7 +410,10 @@ var EndpointRegistry = class {
       }
     }
     if (healthy.length > 0) {
-      return healthy.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+      const sorted = healthy.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+      if (this.strategy === "round-robin") return this.applyRoundRobin(sorted);
+      if (this.strategy === "least-connections") return this.applyLeastConnections(sorted);
+      return sorted;
     }
     return coolingDown.sort((a, b) => a.recoveredAt - b.recoveredAt).map((c) => c.endpoint);
   }
@@ -253,6 +429,10 @@ var EndpointRegistry = class {
   list() {
     return this.endpoints;
   }
+  /** True if any configured endpoint restricts itself to a `models` allow-list. */
+  hasModelScopedEndpoints() {
+    return this.endpoints.some((ep) => ep.models !== void 0);
+  }
   status() {
     const currentTime = this.now();
     return this.endpoints.map((ep) => {
@@ -263,7 +443,8 @@ var EndpointRegistry = class {
         endpoint: ep,
         failureCount: failures,
         ...lastFail !== void 0 ? { lastFailureTimestamp: lastFail } : {},
-        isCoolingDown
+        isCoolingDown,
+        activeRequests: this.activeCounts.get(ep.name) ?? 0
       };
     });
   }
@@ -820,6 +1001,7 @@ function aggregateChat(accumulated, chunk) {
     },
     model: chunk.model,
     done: chunk.done,
+    doneReason: chunk.done ? chunk.done_reason : accumulated.doneReason,
     totalDurationMs: chunk.done && chunk.total_duration !== void 0 ? chunk.total_duration / NANOS_PER_MS : accumulated.totalDurationMs,
     usage: chunk.done ? extractUsage(chunk) : accumulated.usage,
     raw: chunk
@@ -869,6 +1051,7 @@ function aggregateGenerate(accumulated, chunk) {
     response: accumulated.response + (chunk.response ?? ""),
     model: chunk.model,
     done: chunk.done,
+    doneReason: chunk.done ? chunk.done_reason : accumulated.doneReason,
     totalDurationMs: chunk.done && chunk.total_duration !== void 0 ? chunk.total_duration / NANOS_PER_MS : accumulated.totalDurationMs,
     usage: chunk.done ? extractUsage(chunk) : accumulated.usage,
     raw: chunk
@@ -1020,7 +1203,7 @@ var ModelsClient = class {
           });
           return normalizeProgressStream(stream);
         },
-        { ...request, singleEndpoint: true }
+        { ...request, singleEndpoint: true, holdUntil: (stream) => stream.finalResult }
       );
     }
     return this.runner(
@@ -1043,7 +1226,7 @@ var ModelsClient = class {
           });
           return normalizeProgressStream(stream);
         },
-        { ...request, singleEndpoint: true }
+        { ...request, singleEndpoint: true, holdUntil: (stream) => stream.finalResult }
       );
     }
     return this.runner(
@@ -1066,7 +1249,7 @@ var ModelsClient = class {
           });
           return normalizeProgressStream(stream);
         },
-        { ...request, singleEndpoint: true }
+        { ...request, singleEndpoint: true, holdUntil: (stream) => stream.finalResult }
       );
     }
     return this.runner(
@@ -1157,6 +1340,16 @@ var OpenAICompatClient = class {
       signal
     });
   }
+  async createResponses(request, signal) {
+    return this.http.request({
+      path: "/v1/responses",
+      body: request,
+      signal
+    });
+  }
+  async responses(request, signal) {
+    return this.createResponses(request, signal);
+  }
 };
 
 // src/integrations/anthropic.ts
@@ -1177,6 +1370,32 @@ var AnthropicCompatClient = class {
   }
 };
 
+// src/utils.ts
+async function encodeImage(image) {
+  if (typeof image === "string") return image;
+  const bufferCtor = globalThis.Buffer;
+  if (bufferCtor !== void 0) return bufferCtor.from(image).toString("base64");
+  const CHUNK_SIZE = 32768;
+  let binary = "";
+  for (let i = 0; i < image.length; i += CHUNK_SIZE) {
+    binary += String.fromCharCode(...image.subarray(i, i + CHUNK_SIZE));
+  }
+  return btoa(binary);
+}
+async function encodeImages(images) {
+  if (images === void 0) return void 0;
+  return Promise.all(images.map((image) => encodeImage(image)));
+}
+async function withEncodedImages(req) {
+  if (!req.images?.some((image) => image instanceof Uint8Array)) return req;
+  return { ...req, images: await encodeImages(req.images) };
+}
+async function withEncodedMessageImages(messages) {
+  if (!messages.some((message) => message.images?.some((image) => image instanceof Uint8Array)))
+    return messages;
+  return Promise.all(messages.map((message) => withEncodedImages(message)));
+}
+
 // src/client.ts
 var OllamaClient = class {
   registry;
@@ -1186,17 +1405,27 @@ var OllamaClient = class {
   failoverCodes;
   fetchImpl;
   logger;
+  /**
+   * API key for Ollama's hosted web tools (`webSearch`/`webFetch`), which always target
+   * `OLLAMA_CLOUD_BASE_URL` regardless of `config.endpoints` — an Ollama account API key
+   * is inherently a single global credential, not tied to any one inference endpoint.
+   * Resolved the same way as a single-endpoint `apiKey` (`config.apiKey` falling back to
+   * `OLLAMA_API_KEY`), independent of whether `config.endpoints` was used instead.
+   */
+  cloudApiKey;
   constructor(config = {}) {
     const resolvedApiKey = resolveApiKey(config.apiKey);
-    const endpoints = config.endpoints ?? [
+    this.cloudApiKey = resolvedApiKey;
+    const credentialEndpoints = resolveCredentialEndpoints(config);
+    const endpoints = config.endpoints ?? (credentialEndpoints.length > 0 ? [] : [
       {
         name: "default",
         baseUrl: resolveBaseUrl(config.baseUrl),
         ...resolvedApiKey !== void 0 ? { apiKey: resolvedApiKey } : {},
         ...config.headers !== void 0 ? { headers: config.headers } : {}
       }
-    ];
-    this.registry = new EndpointRegistry(endpoints, config.endpointHealth);
+    ]);
+    this.registry = new EndpointRegistry([...endpoints, ...credentialEndpoints], config.endpointHealth);
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.failoverCodes = new Set(config.failoverOn ?? DEFAULT_FAILOVER_CODES);
     this.fetchImpl = config.fetch ?? globalThis.fetch;
@@ -1225,53 +1454,92 @@ var OllamaClient = class {
   async executeWithFailover(operation, options) {
     const timeout = createTimeoutSignal(options?.timeoutMs ?? this.timeoutMs, options?.signal);
     try {
-      const allCandidates = this.registry.candidates();
-      const candidates = options?.singleEndpoint ? allCandidates.slice(0, 1) : allCandidates;
       let lastError;
-      for (const [attemptIndex, endpoint] of candidates.entries()) {
-        this.logger.debug(`Executing on endpoint "${endpoint.name}" (${endpoint.baseUrl})`);
-        const http = new HttpClient({
-          baseUrl: endpoint.baseUrl,
-          ...endpoint.apiKey !== void 0 ? { apiKey: endpoint.apiKey } : {},
-          ...endpoint.headers !== void 0 ? { headers: endpoint.headers } : {},
-          fetch: this.fetchImpl
-        });
-        try {
-          const result = await withSpan(
-            "ollama.endpoint.attempt",
-            {
-              [ATTR_OLLAMA_ENDPOINT_NAME]: endpoint.name,
-              [ATTR_OLLAMA_ENDPOINT_ATTEMPT]: attemptIndex
-            },
-            () => withRetry(() => operation(http, timeout.signal), this.retryConfig)
+      for (; ; ) {
+        const allCandidates = this.registry.candidates(options?.model);
+        if (allCandidates.length === 0 && options?.model !== void 0 && this.registry.hasModelScopedEndpoints()) {
+          const configured = this.registry.list().flatMap((ep) => ep.models ?? []).filter((m, i, arr) => arr.indexOf(m) === i);
+          throw new OllamaModelRoutingError(
+            `No configured endpoint is authorized for model "${options.model}". ` + (configured.length > 0 ? `Endpoints are scoped to: ${configured.join(", ")}.` : "No endpoint declares a `models` allow-list that includes it.") + " Add or widen an `OllamaEndpoint.models` entry to route this model.",
+            { model: options.model, availableModels: configured }
           );
-          this.registry.reportSuccess(endpoint.name);
-          return result;
-        } catch (err) {
-          const error = err instanceof Error ? err : new Error(String(err));
-          lastError = error;
-          this.registry.reportFailure(endpoint.name);
-          this.logger.warn(`Failed on "${endpoint.name}": ${error.message}`);
-          if (!(error instanceof OllamaClientError && this.failoverCodes.has(error.code)))
-            throw error;
         }
+        const candidates = options?.singleEndpoint ? allCandidates.slice(0, 1) : allCandidates;
+        const runnable = this.registry.filterWithCapacity(candidates);
+        if (runnable.length === 0 && candidates.length > 0) {
+          await this.registry.waitForCapacity(
+            candidates.map((c) => c.name),
+            timeout.signal
+          );
+          continue;
+        }
+        for (const [attemptIndex, endpoint] of runnable.entries()) {
+          this.logger.debug(`Executing on endpoint "${endpoint.name}" (${endpoint.baseUrl})`);
+          const http = new HttpClient({
+            baseUrl: endpoint.baseUrl,
+            ...endpoint.apiKey !== void 0 ? { apiKey: endpoint.apiKey } : {},
+            ...endpoint.headers !== void 0 ? { headers: endpoint.headers } : {},
+            fetch: this.fetchImpl
+          });
+          this.registry.acquire(endpoint.name);
+          let holdPromise;
+          try {
+            const result = await withSpan(
+              "ollama.endpoint.attempt",
+              {
+                [ATTR_OLLAMA_ENDPOINT_NAME]: endpoint.name,
+                [ATTR_OLLAMA_ENDPOINT_ATTEMPT]: attemptIndex
+              },
+              () => withRetry(() => operation(http, timeout.signal), this.retryConfig)
+            );
+            this.registry.reportSuccess(endpoint.name);
+            if (options?.holdUntil) holdPromise = options.holdUntil(result);
+            return result;
+          } catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            lastError = error;
+            this.registry.reportFailure(endpoint.name);
+            this.logger.warn(`Failed on "${endpoint.name}": ${error.message}`);
+            if (!(error instanceof OllamaClientError && this.failoverCodes.has(error.code)))
+              throw error;
+          } finally {
+            if (holdPromise) {
+              void holdPromise.catch(() => void 0).finally(() => this.registry.release(endpoint.name));
+            } else {
+              this.registry.release(endpoint.name);
+            }
+          }
+        }
+        throw lastError ?? new Error("No healthy Ollama endpoints available");
       }
-      throw lastError ?? new Error("No healthy Ollama endpoints available");
     } finally {
       timeout.cancel();
     }
   }
   async chat(req) {
+    const messages = await withEncodedMessageImages(req.messages);
     if (req.stream) {
-      return this.executeWithFailover(async (http, signal) => {
-        if (req.format !== void 0) this.assertStructuredOutputSupported(http.baseUrl, req.model);
-        const stream = await http.requestStream({
-          path: "/api/chat",
-          body: { ...req, stream: true },
-          signal
-        });
-        return normalizeChatStream(stream);
-      }, req);
+      return this.executeWithFailover(
+        async (http, signal) => {
+          if (req.format !== void 0)
+            this.assertStructuredOutputSupported(http.baseUrl, req.model);
+          const stream = await http.requestStream({
+            path: "/api/chat",
+            body: { ...req, messages, stream: true },
+            signal
+          });
+          return normalizeChatStream(stream);
+        },
+        {
+          signal: req.signal,
+          timeoutMs: req.timeoutMs,
+          model: req.model,
+          // The endpoint's concurrency slot must stay held for as long as the stream is
+          // actually being consumed, not just until the initial response/headers arrive
+          // — see `executeWithFailover`'s `holdUntil` doc.
+          holdUntil: (stream) => stream.finalResult
+        }
+      );
     }
     return withSpan(
       `chat ${req.model}`,
@@ -1286,7 +1554,7 @@ var OllamaClient = class {
             this.assertStructuredOutputSupported(http.baseUrl, req.model);
           return http.request({
             path: "/api/chat",
-            body: { ...req, stream: false },
+            body: { ...req, messages, stream: false },
             signal
           });
         }, req);
@@ -1313,34 +1581,44 @@ var OllamaClient = class {
     return parseStructuredOutput(res.message.content, schema);
   }
   async generate(req) {
-    if (req.stream) {
-      return this.executeWithFailover(async (http, signal) => {
-        if (req.format !== void 0) this.assertStructuredOutputSupported(http.baseUrl, req.model);
-        const stream = await http.requestStream({
-          path: "/api/generate",
-          body: { ...req, stream: true },
-          signal
-        });
-        return normalizeGenerateStream(stream);
-      }, req);
+    const encodedReq = await withEncodedImages(req);
+    if (encodedReq.stream) {
+      return this.executeWithFailover(
+        async (http, signal) => {
+          if (encodedReq.format !== void 0)
+            this.assertStructuredOutputSupported(http.baseUrl, encodedReq.model);
+          const stream = await http.requestStream({
+            path: "/api/generate",
+            body: { ...encodedReq, stream: true },
+            signal
+          });
+          return normalizeGenerateStream(stream);
+        },
+        {
+          signal: encodedReq.signal,
+          timeoutMs: encodedReq.timeoutMs,
+          model: encodedReq.model,
+          holdUntil: (stream) => stream.finalResult
+        }
+      );
     }
     return withSpan(
-      `text_completion ${req.model}`,
+      `text_completion ${encodedReq.model}`,
       {
         [ATTR_GEN_AI_SYSTEM]: GEN_AI_SYSTEM_OLLAMA,
         [ATTR_GEN_AI_OPERATION_NAME]: "text_completion",
-        [ATTR_GEN_AI_REQUEST_MODEL]: req.model
+        [ATTR_GEN_AI_REQUEST_MODEL]: encodedReq.model
       },
       async (span) => {
         const res = await this.executeWithFailover((http, signal) => {
-          if (req.format !== void 0)
-            this.assertStructuredOutputSupported(http.baseUrl, req.model);
+          if (encodedReq.format !== void 0)
+            this.assertStructuredOutputSupported(http.baseUrl, encodedReq.model);
           return http.request({
             path: "/api/generate",
-            body: { ...req, stream: false },
+            body: { ...encodedReq, stream: false },
             signal
           });
-        }, req);
+        }, encodedReq);
         span?.setAttributes({
           [ATTR_GEN_AI_RESPONSE_MODEL]: res.model,
           ...res.prompt_eval_count !== void 0 ? { [ATTR_GEN_AI_USAGE_INPUT_TOKENS]: res.prompt_eval_count } : {},
@@ -1396,22 +1674,60 @@ var OllamaClient = class {
   createBlob = (digest, data) => this.models.createBlob(digest, data);
   checkBlob = (digest) => this.models.checkBlob(digest);
   // --- Web Endpoints ---
-  webSearch(req) {
-    return this.executeWithFailover(
-      (http, signal) => http.request({ path: "/api/websearch", body: req, signal }),
+  /**
+   * Ollama's hosted web search tool (`POST https://ollama.com/api/web_search`) — a fixed
+   * Ollama Cloud service, unrelated to `config.endpoints`/`baseUrl` and not proxied
+   * through a local server. Requires an Ollama account API key: pass `apiKey` to the
+   * client constructor or set `OLLAMA_API_KEY`. Applies the same default `timeoutMs` and
+   * retry policy as inference calls, but never cross-endpoint-fails-over — there is only
+   * ever the one cloud endpoint to call.
+   */
+  async webSearch(req) {
+    const { count, max_results, ...rest } = req;
+    const res = await this.executeCloudRequest(
+      (http, signal) => http.request({
+        path: "/api/web_search",
+        body: { ...rest, max_results: max_results ?? count },
+        signal
+      }),
       req
     );
+    return { results: res.results.map((r) => ({ ...r, snippet: r.content })) };
   }
+  /**
+   * Ollama's hosted web fetch tool (`POST https://ollama.com/api/web_fetch`) — see
+   * {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry behavior,
+   * which applies identically here.
+   */
   webFetch(req) {
-    return this.executeWithFailover(
-      (http, signal) => http.request({ path: "/api/webfetch", body: req, signal }),
+    return this.executeCloudRequest(
+      (http, signal) => http.request({ path: "/api/web_fetch", body: req, signal }),
       req
     );
   }
+  /**
+   * Runs `operation` against the fixed Ollama Cloud host with this client's default
+   * timeout and retry policy — the same primitives `executeWithFailover` uses, minus the
+   * multi-candidate loop, since `webSearch`/`webFetch` only ever have the one endpoint.
+   */
+  async executeCloudRequest(operation, options) {
+    const timeout = createTimeoutSignal(options.timeoutMs ?? this.timeoutMs, options.signal);
+    try {
+      const http = new HttpClient({
+        baseUrl: OLLAMA_CLOUD_BASE_URL,
+        apiKey: this.cloudApiKey,
+        fetch: this.fetchImpl
+      });
+      return await withRetry(() => operation(http, timeout.signal), this.retryConfig);
+    } finally {
+      timeout.cancel();
+    }
+  }
   // --- Capabilities & Health ---
   capabilities(model) {
     return this.executeWithFailover((http) => detectModelCapabilities(http, model), {
-      singleEndpoint: true
+      singleEndpoint: true,
+      model
     });
   }
   runtimeMode() {
@@ -1529,6 +1845,117 @@ function toResponse(stream, init = {}) {
   return new Response(body, { ...init, headers });
 }
 
+// src/quota.ts
+var QuotaManager = class {
+  now;
+  windows;
+  constructor(options) {
+    if (options.windows.length === 0) {
+      throw new Error("QuotaManager requires at least one window configuration.");
+    }
+    this.now = options.now ?? Date.now;
+    this.windows = options.windows.map((config) => ({
+      config,
+      tokensUsed: 0,
+      requestsMade: 0,
+      windowStartedAt: this.now()
+    }));
+  }
+  rollover(state) {
+    if (this.now() - state.windowStartedAt >= state.config.windowMs) {
+      state.tokensUsed = 0;
+      state.requestsMade = 0;
+      state.windowStartedAt = this.now();
+    }
+  }
+  /** Current usage, budgets, and reset time for every configured window. */
+  status() {
+    return this.windows.map((state) => {
+      this.rollover(state);
+      const { config } = state;
+      return {
+        ...config,
+        tokensUsed: state.tokensUsed,
+        requestsMade: state.requestsMade,
+        windowStartedAt: state.windowStartedAt,
+        windowResetAt: state.windowStartedAt + config.windowMs,
+        ...config.maxTokens !== void 0 ? { remainingTokens: Math.max(0, config.maxTokens - state.tokensUsed) } : {},
+        ...config.maxRequests !== void 0 ? { remainingRequests: Math.max(0, config.maxRequests - state.requestsMade) } : {}
+      };
+    });
+  }
+  /**
+   * True if one more request — optionally estimated at `estimatedTokens` — would stay
+   * within every configured window's budget. Read-only; does not record usage.
+   */
+  canProceed(estimatedTokens = 0) {
+    return this.windows.every((state) => {
+      this.rollover(state);
+      const { config } = state;
+      if (config.maxRequests !== void 0 && state.requestsMade + 1 > config.maxRequests) {
+        return false;
+      }
+      return !(config.maxTokens !== void 0 && state.tokensUsed + estimatedTokens > config.maxTokens);
+    });
+  }
+  /**
+   * Throws `OllamaQuotaExceededError` for the first window that `canProceed(estimatedTokens)`
+   * would fail on; otherwise a no-op. Call before issuing a request.
+   */
+  assertCanProceed(estimatedTokens = 0) {
+    for (const state of this.windows) {
+      this.rollover(state);
+      const { config } = state;
+      if (config.maxRequests !== void 0 && state.requestsMade + 1 > config.maxRequests) {
+        throw new OllamaQuotaExceededError(
+          `Client-side quota window "${config.id}" would exceed its request budget (${state.requestsMade}/${config.maxRequests} requests used).`,
+          { windowId: config.id, resetAt: state.windowStartedAt + config.windowMs }
+        );
+      }
+      if (config.maxTokens !== void 0 && state.tokensUsed + estimatedTokens > config.maxTokens) {
+        throw new OllamaQuotaExceededError(
+          `Client-side quota window "${config.id}" would exceed its token budget (${state.tokensUsed}/${config.maxTokens} tokens used).`,
+          { windowId: config.id, resetAt: state.windowStartedAt + config.windowMs }
+        );
+      }
+    }
+  }
+  /** Records one request's actual usage — a raw API response or a pre-normalized `TokenUsage` — against every window. */
+  recordUsage(usage) {
+    const normalized = "totalTokens" in usage ? usage : extractUsage(usage);
+    for (const state of this.windows) {
+      this.rollover(state);
+      state.tokensUsed += normalized.totalTokens;
+      state.requestsMade += 1;
+    }
+  }
+  /** Resets one window (by `id`) or, if omitted, all windows — zeroing usage and restarting their clocks. */
+  reset(windowId) {
+    for (const state of this.windows) {
+      if (windowId === void 0 || state.config.id === windowId) {
+        state.tokensUsed = 0;
+        state.requestsMade = 0;
+        state.windowStartedAt = this.now();
+      }
+    }
+  }
+};
+function createOllamaCloudFreeTierQuota(budgets) {
+  const windows = [];
+  if (budgets.session !== void 0) {
+    windows.push({ id: "session", windowMs: 5 * 60 * 60 * 1e3, ...budgets.session });
+  }
+  if (budgets.weekly !== void 0) {
+    windows.push({ id: "weekly", windowMs: 7 * 24 * 60 * 60 * 1e3, ...budgets.weekly });
+  }
+  if (windows.length === 0) {
+    throw new Error(
+      "createOllamaCloudFreeTierQuota requires at least a `session` or `weekly` budget."
+    );
+  }
+  return new QuotaManager({ windows, ...budgets.now !== void 0 ? { now: budgets.now } : {} });
+}
+
 // src/tools/define-tool.ts
 function defineTool(options) {
   const jsonSchema = zodToJsonSchema(options.schema);
@@ -1964,6 +2391,6 @@ var Agent = class {
   }
 };
 
-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, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_FAILOVER_CODES, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAuthError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaMcpError, OllamaNetworkError, OllamaNotFoundError, OllamaRateLimitError, OllamaServerError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAICompatClient, ToolRegistry, addSpanEvent, applySkill, calculateBackoff, checkEndpointHealth, composeMiddleware, createConsoleLogger, createTimeoutSignal, defineTool, detectModelCapabilities, extractUsage, inferRuntimeMode, listAvailableModels, loadMcpTools, mapError, normalizeChatStream, normalizeGenerateStream, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseStructuredOutput, registerMcpTools, 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, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_FAILOVER_CODES, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, EndpointRegistry, GEN_AI_SYSTEM_OLLAMA, HttpClient, ModelsClient, NANOS_PER_MS, NANOS_PER_SECOND, NOOP_LOGGER, OLLAMA_CLOUD_BASE_URL, OllamaAbortError, OllamaAgentMaxIterationsError, OllamaAuthError, OllamaClient, OllamaClientError, OllamaGenericClientError, OllamaMcpError, OllamaModelRoutingError, OllamaNetworkError, OllamaNotFoundError, OllamaQuotaExceededError, OllamaRateLimitError, OllamaServerError, OllamaSkillInvalidError, OllamaSkillNotFoundError, OllamaStream, OllamaTimeoutError, OllamaToolTimeoutError, OllamaToolValidationError, OllamaUnsupportedCapabilityError, OpenAICompatClient, QuotaManager, ToolRegistry, addSpanEvent, applySkill, calculateBackoff, checkEndpointHealth, composeMiddleware, createConsoleLogger, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, encodeImage, extractUsage, inferRuntimeMode, listAvailableModels, loadMcpTools, mapError, normalizeChatStream, normalizeGenerateStream, normalizeProgressStream, parseFrontmatter, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveCredentialEndpoints, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map