@nemesis-oss/ollama-sdk 1.8.0 → 1.10.0

package/dist/index.cjs

@@ -48,6 +48,47 @@ var __callDispose = (stack, error, hasError) => {
   return next();
 };
 
+// src/transport/host.ts
+var DEFAULT_PORT = "11434";
+var SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+function normalizeBaseUrl(host) {
+  const trimmed = host.trim();
+  if (trimmed === "") return trimmed;
+  const implicitScheme = !SCHEME_RE.test(trimmed);
+  const withHost = trimmed.startsWith(":") ? `127.0.0.1${trimmed}` : trimmed;
+  const candidate = implicitScheme ? `http://${withHost}` : withHost;
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    return trimmed.replace(/\/+$/, "");
+  }
+  let protocol = url.protocol;
+  let port = url.port;
+  if (implicitScheme) {
+    if (port === "443") {
+      protocol = "https:";
+      port = "";
+    } else if (port === "") {
+      port = DEFAULT_PORT;
+    }
+  }
+  const authority = `${url.hostname}${port !== "" ? `:${port}` : ""}`;
+  return `${protocol}//${authority}${url.pathname}`.replace(/\/+$/, "");
+}
+function isEnvApiKeyHost(baseUrl) {
+  let hostname;
+  try {
+    hostname = new URL(normalizeBaseUrl(baseUrl)).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  if (hostname === "ollama.com" || hostname.endsWith(".ollama.com")) return true;
+  if (hostname === "localhost" || hostname.endsWith(".localhost")) return true;
+  if (hostname === "[::1]" || hostname === "::1" || hostname === "0.0.0.0") return true;
+  return /^127(?:\.\d{1,3}){3}$/.test(hostname);
+}
+
 // src/config.ts
 var DEFAULT_BASE_URL = "http://localhost:11434";
 var DEFAULT_TIMEOUT_MS = 3e4;
@@ -56,11 +97,16 @@ function readEnv(name) {
   return typeof process !== "undefined" && process.env ? process.env[name] : void 0;
 }
 function resolveBaseUrl(configBaseUrl) {
-  return configBaseUrl ?? readEnv("OLLAMA_HOST") ?? DEFAULT_BASE_URL;
+  return normalizeBaseUrl(configBaseUrl ?? readEnv("OLLAMA_HOST") ?? DEFAULT_BASE_URL);
 }
 function resolveApiKey(configApiKey) {
   return configApiKey ?? readEnv("OLLAMA_API_KEY");
 }
+function resolveEndpointApiKey(configApiKey, baseUrl) {
+  if (configApiKey !== void 0) return configApiKey;
+  const envKey = readEnv("OLLAMA_API_KEY");
+  return envKey !== void 0 && isEnvApiKeyHost(baseUrl) ? envKey : void 0;
+}
 function resolveCredentialEndpoints(config) {
   if (config.credentials === void 0) return [];
   const modelsByCredential = /* @__PURE__ */ new Map();
@@ -93,6 +139,18 @@ var DEFAULT_FAILOVER_CODES = [
   "network_error",
   "timeout",
   "server_error",
+  // HTTP 503 — server queue saturated (OLLAMA_MAX_QUEUE exceeded).
+  // The new OllamaOverloadedError specialization is retryable: the
+  // queue will eventually drain, and a different candidate endpoint
+  // may have capacity right now. Listed separately from
+  // 'server_error' because OllamaOverloadedError extends
+  // OllamaClientError (NOT OllamaServerError) — see
+  // src/errors.ts for the rationale.
+  "overloaded",
+  // HTTP 502 — cloud model could not be reached by the Ollama Cloud
+  // proxy. Fail over to a different model/endpoint rather than
+  // retrying the same one.
+  "bad_gateway",
   "rate_limited",
   "auth_error",
   // A candidate endpoint rejected the request pre-flight for a known-unsupported
@@ -161,6 +219,24 @@ var OllamaServerError = class extends OllamaClientError {
     super(message, { ...options, code: "server_error", retryable: true });
   }
 };
+var OllamaOverloadedError = class extends OllamaClientError {
+  constructor(message, options) {
+    super(message, { ...options, code: "overloaded", status: 503, retryable: true });
+  }
+};
+var OllamaBadGatewayError = class extends OllamaClientError {
+  constructor(message, options) {
+    super(message, { ...options, code: "bad_gateway", status: 502, retryable: true });
+  }
+};
+var OllamaStreamError = class extends OllamaClientError {
+  /** Content accumulated before the in-band error frame, or '' if none. */
+  partialContent;
+  constructor(message, options) {
+    super(message, { ...options, code: "stream_error", retryable: false });
+    this.partialContent = options?.partialContent ?? "";
+  }
+};
 var OllamaAbortError = class extends OllamaClientError {
   constructor(message, options) {
     super(message, { ...options, code: "aborted", retryable: false });
@@ -310,6 +386,12 @@ function statusToError(status, message, options) {
   if (status === 429) {
     return new OllamaRateLimitError(message, { ...options, status });
   }
+  if (status === 502) {
+    return new OllamaBadGatewayError(message, { ...options });
+  }
+  if (status === 503) {
+    return new OllamaOverloadedError(message, { ...options });
+  }
   if (status >= 500) {
     return new OllamaServerError(message, { ...options, status });
   }
@@ -580,6 +662,75 @@ function composeMiddleware(middlewares, finalHandler) {
   };
 }
 
+// src/vision.ts
+var DATA_URI_PATTERN = /^data:image\/[a-z0-9.+-]+;base64,/i;
+var IMAGE_FILE_EXTENSION_PATTERN = /\.(png|jpe?g|webp|gif|bmp|tiff?|avif)$/i;
+function imageStringNeedsResolution(input) {
+  return DATA_URI_PATTERN.test(input) || input.startsWith("http://") || input.startsWith("https://") || IMAGE_FILE_EXTENSION_PATTERN.test(input);
+}
+function hasNodeFs() {
+  return typeof process !== "undefined" && process !== null && typeof process.versions?.node === "string";
+}
+var NODE_FS_MODULE = "node:fs";
+async function readFileAsBase64(path) {
+  const { promises: fs } = await import(NODE_FS_MODULE);
+  const data = await fs.readFile(path);
+  return data.toString("base64");
+}
+async function fetchUrlAsBase64(url, signal) {
+  const res = await fetch(url, signal !== void 0 ? { signal } : void 0);
+  if (!res.ok) {
+    throw new OllamaClientError(
+      `Failed to fetch image from URL "${url}": HTTP ${res.status} ${res.statusText}.`,
+      { code: "image_fetch_failed" }
+    );
+  }
+  const arrayBuffer = await res.arrayBuffer();
+  return encodeBytesBase64(new Uint8Array(arrayBuffer));
+}
+function encodeBytesBase64(bytes) {
+  const bufferCtor = globalThis.Buffer;
+  if (bufferCtor !== void 0) return bufferCtor.from(bytes).toString("base64");
+  const CHUNK_SIZE = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK_SIZE));
+  }
+  return btoa(binary);
+}
+async function resolveImageInput(input, signal) {
+  if (typeof input !== "string") {
+    return encodeBytesBase64(input instanceof Uint8Array ? input : new Uint8Array(input));
+  }
+  if (DATA_URI_PATTERN.test(input)) {
+    return input.replace(DATA_URI_PATTERN, "").trim();
+  }
+  if (input.startsWith("http://") || input.startsWith("https://")) {
+    return fetchUrlAsBase64(input, signal);
+  }
+  if (IMAGE_FILE_EXTENSION_PATTERN.test(input)) {
+    if (!hasNodeFs()) {
+      throw new OllamaClientError(
+        `Vision input "${input}" looks like a local file path, but this runtime has no Node.js \`fs\` module (browser/edge). Read the file into bytes yourself and pass the \`Uint8Array\`, or pass a base64 string / data URI / http(s) URL instead.`,
+        { code: "vision_path_unsupported_runtime" }
+      );
+    }
+    try {
+      return await readFileAsBase64(input);
+    } catch {
+      return input;
+    }
+  }
+  return input.trim();
+}
+async function resolveImages(images, signal) {
+  if (images === void 0) return void 0;
+  if (images.every((image) => typeof image === "string" && !imageStringNeedsResolution(image))) {
+    return images;
+  }
+  return Promise.all(images.map((image) => resolveImageInput(image, signal)));
+}
+
 // src/utils.ts
 async function encodeImage(image) {
   if (typeof image === "string") return image;
@@ -592,18 +743,22 @@ async function encodeImage(image) {
   }
   return btoa(binary);
 }
-async function encodeImages(images) {
-  if (images === void 0) return void 0;
-  return Promise.all(images.map((image) => encodeImage(image)));
+async function encodeImages(images, signal) {
+  return resolveImages(images, signal);
 }
-async function withEncodedImages(req) {
-  if (!req.images?.some((image) => image instanceof Uint8Array)) return req;
-  return { ...req, images: await encodeImages(req.images) };
+async function withEncodedImages(req, signal) {
+  const needsResolution = req.images?.some(
+    (image) => typeof image !== "string" || imageStringNeedsResolution(image)
+  );
+  if (!needsResolution) return req;
+  return { ...req, images: await encodeImages(req.images ?? [], signal) };
 }
-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)));
+async function withEncodedMessageImages(messages, signal) {
+  const needsResolution = messages.some(
+    (message) => message.images?.some((image) => typeof image !== "string" || imageStringNeedsResolution(image))
+  );
+  if (!needsResolution) return messages;
+  return Promise.all(messages.map((message) => withEncodedImages(message, signal)));
 }
 function disposableTimer(timer) {
   return {
@@ -632,6 +787,12 @@ function disposableSpan(span) {
 }
 
 // src/streaming/ndjson.ts
+function isInBandErrorFrame(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  if (typeof record.error !== "string" || record.error.length === 0) return false;
+  return !("model" in record) && !("response" in record) && !("message" in record) && !("status" in record) && !("done" in record);
+}
 async function* parseNdjsonStream(stream) {
   var _stack = [];
   try {
@@ -648,17 +809,34 @@ async function* parseNdjsonStream(stream) {
       for (const line of lines) {
         const trimmed = line.trim();
         if (!trimmed) continue;
+        let json;
         try {
-          yield JSON.parse(trimmed);
+          json = JSON.parse(trimmed);
         } catch (err) {
           throw new OllamaGenericClientError(`Failed to parse stream JSON chunk: ${trimmed}`, {
             cause: err
           });
         }
+        if (isInBandErrorFrame(json)) {
+          throw new OllamaStreamError(json.error);
+        }
+        yield json;
       }
     }
     if (buffer.trim()) {
-      yield JSON.parse(buffer.trim());
+      const trimmed = buffer.trim();
+      let json;
+      try {
+        json = JSON.parse(trimmed);
+      } catch (err) {
+        throw new OllamaGenericClientError(`Failed to parse stream JSON chunk: ${trimmed}`, {
+          cause: err
+        });
+      }
+      if (isInBandErrorFrame(json)) {
+        throw new OllamaStreamError(json.error);
+      }
+      yield json;
     }
   } catch (_) {
     var _error = _, _hasError = true;
@@ -869,7 +1047,7 @@ var HttpClient = class {
   onLifecycleEvent;
   requestId;
   constructor(options) {
-    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.baseUrl = normalizeBaseUrl(options.baseUrl);
     this.apiKey = options.apiKey;
     this.defaultHeaders = options.headers ?? {};
     this.fetchImpl = options.fetch ?? globalThis.fetch;
@@ -1258,7 +1436,7 @@ async function checkEndpointHealth(endpoint, fetchImpl, timeoutMs = 5e3, middlew
 function inferRuntimeMode(baseUrl) {
   try {
     const url = new URL(baseUrl);
-    const host = url.hostname.toLowerCase();
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
     if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".local") || host.startsWith("192.168.") || host.startsWith("10.")) {
       return "local";
     }
@@ -1276,6 +1454,63 @@ function extractContextLength(modelInfo) {
   }
   return void 0;
 }
+function extractModelFamily(showRes) {
+  if (showRes.model_info) {
+    for (const [key, value] of Object.entries(showRes.model_info)) {
+      if (key.endsWith(".architecture") && typeof value === "string" && value.length > 0) {
+        return value.toLowerCase();
+      }
+    }
+  }
+  if (showRes.details?.family && showRes.details.family.length > 0) {
+    return showRes.details.family.toLowerCase();
+  }
+  const families = showRes.details?.families;
+  if (families && families.length > 0) {
+    const first = families[0];
+    if (typeof first === "string" && first.length > 0) return first.toLowerCase();
+  }
+  return void 0;
+}
+var PARALLEL_TOOL_CALL_LOCAL_FAMILIES = /* @__PURE__ */ new Set([
+  "qwen2",
+  "qwen2.5",
+  "qwen3",
+  "llama3.1",
+  "llama3.2",
+  "llama3.3",
+  "llama4",
+  "mistral",
+  "mixtral",
+  "hermes",
+  "command-r",
+  "command-r-plus"
+]);
+var PARALLEL_TOOL_CALL_NAME_HINTS = /* @__PURE__ */ new Set([
+  "tool-use",
+  "tooluse",
+  "function-call",
+  "functioncall",
+  "instruct",
+  // Most "instruct" variants of tool-capable families ship with parallel tool calls
+  "hermes",
+  "command-r"
+]);
+function inferLocalParallelToolCalls(model, family) {
+  const modelLower = model.toLowerCase();
+  if (family !== void 0 && PARALLEL_TOOL_CALL_LOCAL_FAMILIES.has(family)) {
+    return "yes";
+  }
+  for (const hint of PARALLEL_TOOL_CALL_NAME_HINTS) {
+    if (modelLower.includes(hint)) {
+      return "yes";
+    }
+  }
+  return "unknown";
+}
+function inferCloudParallelToolCalls(supportsTools) {
+  return supportsTools ? "yes" : "unknown";
+}
 async function detectModelCapabilities(http, model, signal) {
   const showRes = await http.request({
     path: "/api/show",
@@ -1285,10 +1520,16 @@ async function detectModelCapabilities(http, model, signal) {
   const reported = showRes.capabilities ?? [];
   const reportedSet = new Set(reported.map((c) => c.toLowerCase()));
   const contextLength = extractContextLength(showRes.model_info);
+  const supportsTools = reportedSet.has("tools");
+  const runtimeMode = inferRuntimeMode(http.baseUrl);
+  const parallelToolCalls = runtimeMode === "cloud" ? inferCloudParallelToolCalls(supportsTools) : runtimeMode === "local" ? inferLocalParallelToolCalls(model, extractModelFamily(showRes)) : (
+    // unknown runtime mode — can't even tell if we're cloud or local
+    "unknown"
+  );
   return {
     model,
     reported,
-    supportsTools: reportedSet.has("tools"),
+    supportsTools,
     supportsVision: reportedSet.has("vision"),
     supportsEmbedding: reportedSet.has("embedding"),
     supportsCompletion: reportedSet.has("completion") || !reportedSet.has("embedding"),
@@ -1296,7 +1537,8 @@ async function detectModelCapabilities(http, model, signal) {
     ...showRes.thinking !== void 0 ? { thinking: showRes.thinking } : {},
     ...contextLength !== void 0 ? { contextLength } : {},
     supportsStreaming: true,
-    supportsStructuredOutputRequest: inferRuntimeMode(http.baseUrl) !== "cloud"
+    supportsStructuredOutputRequest: runtimeMode !== "cloud",
+    parallelToolCalls
   };
 }
 async function listAvailableModels(http) {
@@ -1441,7 +1683,131 @@ function ensureToolCallIds(toolCalls) {
   return toolCalls.map((tc) => tc.id !== void 0 ? tc : { ...tc, id: generateToolCallId() });
 }
 
+// src/tools/tool-call-accumulator.ts
+function isSameToolCall(a, b, aIndex, bIndex) {
+  if (a.id !== void 0 && b.id !== void 0) {
+    return a.id === b.id;
+  }
+  if (aIndex !== void 0 && bIndex !== void 0) {
+    return aIndex === bIndex;
+  }
+  return false;
+}
+function mergeToolCall(earlier, later) {
+  const earlierFn = earlier.function;
+  const laterFn = later.function;
+  const earlierArgs = earlierFn.arguments;
+  const laterArgs = laterFn.arguments;
+  const mergedFn = {
+    name: laterFn.name || earlierFn.name,
+    arguments: earlierArgs !== void 0 && laterArgs !== void 0 ? { ...earlierArgs, ...laterArgs } : laterArgs ?? earlierArgs ?? {}
+  };
+  return {
+    // id: prefer the later one if present, else the earlier one
+    ...later.id !== void 0 ? { id: later.id } : earlier.id !== void 0 ? { id: earlier.id } : {},
+    function: mergedFn
+  };
+}
+function mergeToolCallArgumentsString(earlier, later) {
+  const earlierArgs = earlier.function.arguments;
+  const laterArgs = later.function.arguments;
+  const concatenated = (typeof earlierArgs === "string" ? earlierArgs : "") + (typeof laterArgs === "string" ? laterArgs : "");
+  return {
+    ...later.id !== void 0 ? { id: later.id } : earlier.id !== void 0 ? { id: earlier.id } : {},
+    function: {
+      name: later.function.name || earlier.function.name,
+      arguments: concatenated
+    }
+  };
+}
+var ToolCallAccumulator = class {
+  entries = [];
+  /**
+   * Process a chunk's `tool_calls` array. Entries that match an
+   * existing accumulated entry (by id or array position) are merged;
+   * new entries are appended.
+   *
+   * Returns the current accumulated state (a shallow copy — entries
+   * themselves are NOT deep-cloned, so callers that mutate
+   * `function.arguments` on a returned entry will mutate the
+   * accumulator's internal state. Use {@link snapshot} for an
+   * explicitly read-only view, or deep-clone the result if you need
+   * full isolation).
+   */
+  process(toolCalls) {
+    if (!toolCalls || toolCalls.length === 0) {
+      return [...this.entries];
+    }
+    for (let i = 0; i < toolCalls.length; i++) {
+      const incoming = toolCalls[i];
+      if (!incoming) continue;
+      let matchedIndex = -1;
+      for (let j = 0; j < this.entries.length; j++) {
+        const existing = this.entries[j];
+        if (existing && isSameToolCall(existing, incoming, j, i)) {
+          matchedIndex = j;
+          break;
+        }
+      }
+      if (matchedIndex >= 0) {
+        this.entries[matchedIndex] = mergeToolCall(this.entries[matchedIndex], incoming);
+      } else {
+        this.entries.push(incoming);
+      }
+    }
+    return [...this.entries];
+  }
+  /**
+   * Returns the final accumulated tool calls. Identical to calling
+   * `process(undefined)` — included for ergonomics so callers can
+   * express "I'm done, give me the result" without a no-op call.
+   *
+   * The returned array is a shallow copy; entries themselves are
+   * the same object references the accumulator holds internally.
+   */
+  finalize() {
+    return [...this.entries];
+  }
+  /**
+   * Returns the current accumulated state without modifying the
+   * accumulator. Useful for mid-stream inspection.
+   *
+   * The returned array is a shallow copy; mutating it (e.g.
+   * `result.push(...)`) does not affect the accumulator, but
+   * mutating an entry's `function.arguments` object DOES affect
+   * the accumulator's internal state because the entry reference
+   * is shared. Deep-clone the result if you need full isolation.
+   */
+  snapshot() {
+    return [...this.entries];
+  }
+  /**
+   * Returns the number of accumulated tool calls so far.
+   */
+  get length() {
+    return this.entries.length;
+  }
+};
+function mergeToolCallArrays(earlier, later) {
+  const acc = new ToolCallAccumulator();
+  acc.process(earlier);
+  acc.process(later);
+  return acc.finalize();
+}
+
 // src/streaming/stream.ts
+function extractPartialContent(accumulated) {
+  if (typeof accumulated !== "object" || accumulated === null) return "";
+  const record = accumulated;
+  const message = record.message;
+  if (typeof message === "object" && message !== null) {
+    const content = message.content;
+    if (typeof content === "string") return content;
+  }
+  const response = record.response;
+  if (typeof response === "string") return response;
+  return "";
+}
 var OllamaStream = class {
   constructor(source, mapChunk, aggregate, initial, signal) {
     this.source = source;
@@ -1462,10 +1828,6 @@ var OllamaStream = class {
       }
     }
   }
-  source;
-  mapChunk;
-  aggregate;
-  initial;
   mode = "unconsumed";
   listeners = /* @__PURE__ */ new Map();
   finalResultPromise;
@@ -1524,7 +1886,10 @@ var OllamaStream = class {
     } catch (error) {
       this.removeAbortListener?.();
       this.removeAbortListener = void 0;
-      const mapped = mapError(error);
+      const mapped = error instanceof OllamaStreamError && error.partialContent === "" ? new OllamaStreamError(error.message, {
+        partialContent: extractPartialContent(accumulated),
+        cause: error
+      }) : mapError(error);
       this.emit({ type: "error", data: { error: mapped } });
       this.rejectFinal(mapped);
     }
@@ -1551,7 +1916,10 @@ var OllamaStream = class {
         }
       }
     } catch (error) {
-      const mapped = mapError(error);
+      const mapped = error instanceof OllamaStreamError && error.partialContent === "" ? new OllamaStreamError(error.message, {
+        partialContent: extractPartialContent(accumulated),
+        cause: error
+      }) : mapError(error);
       this.rejectFinal(mapped);
       yield { type: "error", data: { error: mapped } };
     } finally {
@@ -1573,7 +1941,17 @@ function aggregateChat(accumulated, chunk) {
       role: message.role || accumulated.message.role,
       content: accumulated.message.content + (message.content ?? ""),
       thinking: message.thinking !== void 0 ? (accumulated.message.thinking ?? "") + message.thinking : accumulated.message.thinking,
-      tool_calls: message.tool_calls?.length ? [...accumulated.message.tool_calls ?? [], ...message.tool_calls] : accumulated.message.tool_calls
+      // Defensive tool-call merging: instead of blindly appending
+      // every chunk's tool_calls array (which would produce
+      // duplicates if Ollama ever starts streaming them
+      // incrementally), merge entries that refer to the same logical
+      // call (matched by id or array position). For the documented
+      // native behavior (tool_calls arrive complete in one chunk)
+      // this is a no-op — the accumulator appends exactly once.
+      //
+      // See src/tools/tool-call-accumulator.ts for the full merge
+      // semantics and the rationale.
+      tool_calls: message.tool_calls?.length || accumulated.message.tool_calls?.length ? mergeToolCallArrays(accumulated.message.tool_calls, message.tool_calls) : void 0
     },
     model: chunk.model,
     done: chunk.done,
@@ -1782,12 +2160,24 @@ function createTimeoutSignal(timeoutMs, userSignal) {
   return { signal: controller.signal, cancel };
 }
 
+// src/keep-alive.ts
+var KEEP_ALIVE_UNLOAD = 0;
+var KEEP_ALIVE_INDEFINITE = -1;
+function normalizeKeepAlive(keepAlive) {
+  if (keepAlive === void 0) return void 0;
+  if (keepAlive === "unload") return KEEP_ALIVE_UNLOAD;
+  if (keepAlive === "indefinite") return KEEP_ALIVE_INDEFINITE;
+  return keepAlive;
+}
+function isKeepAliveSugar(value) {
+  return value === "unload" || value === "indefinite";
+}
+
 // src/models-client.ts
 var ModelsClient = class {
   constructor(runner) {
     this.runner = runner;
   }
-  runner;
   list() {
     return this.runner((http) => listAvailableModels(http), { singleEndpoint: true });
   }
@@ -1894,6 +2284,76 @@ var ModelsClient = class {
       { singleEndpoint: true }
     );
   }
+  /**
+   * Immediately unloads `model` from VRAM/RAM by issuing an empty
+   * `/api/generate` request with `keep_alive: 0`. The server
+   * finalizes any in-flight generation, releases the model's
+   * weights from GPU memory, and frees the slot for subsequent
+   * pipelines (e.g. swap a vision encoder out before loading an
+   * LLM).
+   *
+   * This is the ergonomic equivalent of:
+   *
+   * ```ts
+   * client.generate({ model, prompt: '', keep_alive: 0 });
+   * ```
+   *
+   * Use {@link pin} for the opposite lifecycle — pinning a model
+   * indefinitely in VRAM for hot-loop inference.
+   *
+   * Resolves once the server acknowledges the unload. The promise
+   * rejects on transport errors, model-not-found (404), or auth
+   * failures — callers handling transient issues can retry via the
+   * standard {@link withRetry} policy.
+   *
+   * See: https://github.com/ollama/ollama/blob/main/docs/faq.md
+   *      #how-do-i-keep-a-model-loaded-in-memory-or-make-it-unload-immediately
+   */
+  async unload(model) {
+    await this.runner(
+      (http, signal) => http.request({
+        path: "/api/generate",
+        body: { model, prompt: "", keep_alive: KEEP_ALIVE_UNLOAD, stream: false },
+        signal
+      }),
+      { model, singleEndpoint: true }
+    );
+  }
+  /**
+   * Pre-loads and pins `model` into VRAM indefinitely by issuing an
+   * empty `/api/generate` request with `keep_alive: -1`. The server
+   * loads the model into GPU memory (paying the cold-load latency
+   * once) and keeps it resident until either:
+   *
+   *   - an explicit {@link unload} call is made,
+   *   - the server process is restarted, or
+   *   - the host runs out of VRAM and the server's own eviction
+   *     policy kicks in.
+   *
+   * This is the ergonomic equivalent of:
+   *
+   * ```ts
+   * client.generate({ model, prompt: '', keep_alive: -1 });
+   * ```
+   *
+   * Use {@link unload} to release the pinned slot when the hot loop
+   * is done — leaving models pinned indefinitely exhausts VRAM and
+   * starves subsequent pipelines.
+   *
+   * Resolves once the server acknowledges the pin (i.e. the model
+   * is fully loaded). The promise rejects on transport errors,
+   * model-not-found (404), or VRAM-exhaustion failures.
+   */
+  async pin(model) {
+    await this.runner(
+      (http, signal) => http.request({
+        path: "/api/generate",
+        body: { model, prompt: "", keep_alive: KEEP_ALIVE_INDEFINITE, stream: false },
+        signal
+      }),
+      { model, singleEndpoint: true }
+    );
+  }
   async createBlob(digest, data) {
     await this.runner(
       (http, signal) => http.request({
@@ -1921,6 +2381,100 @@ var ModelsClient = class {
       throw err;
     }
   }
+  /**
+   * Computes a blob digest the way Ollama's content-addressed store expects:
+   * SHA-256 over the raw bytes, formatted as `sha256:<64 lowercase hex>`.
+   *
+   * Uses the Web Crypto API (`crypto.subtle.digest`), which exists in every
+   * supported runtime — Node.js ≥ 19 exposes it as a global (this SDK
+   * requires Node ≥ 20), and browsers/edge runtimes have always had it.
+   */
+  async computeBlobDigest(data) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === void 0) {
+      throw new OllamaClientError(
+        "computeBlobDigest requires the Web Crypto API (crypto.subtle), unavailable in this runtime.",
+        { code: "crypto_unavailable" }
+      );
+    }
+    const digestBytes = await subtle.digest("SHA-256", data);
+    const hex = Array.from(
+      new Uint8Array(digestBytes),
+      (byte) => byte.toString(16).padStart(2, "0")
+    ).join("");
+    return `sha256:${hex}`;
+  }
+  /**
+   * Computes the SHA-256 digest of `data` and pushes it as a blob in one
+   * step — the content-addressed upload Ollama's own tooling performs
+   * (`curl -T file http://…/api/blobs/sha256:…`). Returns the digest, which
+   * `/api/create`'s `files` field references.
+   *
+   * Pass `digest` to skip recomputation when the caller already knows it —
+   * the server verifies the content against the digest and rejects mismatches.
+   */
+  async createBlobFromData(data, opts) {
+    const digest = opts?.digest ?? await this.computeBlobDigest(data);
+    const alreadyExisted = await this.checkBlob(digest);
+    if (!alreadyExisted) {
+      await this.createBlob(digest, data);
+    }
+    return { digest, alreadyExisted };
+  }
+  /**
+   * Reads a local file and uploads it as a blob (Node.js only — dynamic
+   * `node:fs` import, so browser bundles never pull it in). The file name
+   * (basename) is what `/api/create`'s `files` map expects as the key, so
+   * this returns it alongside the digest.
+   */
+  async createBlobFromFile(path, opts) {
+    const nodeFsModule = "node:fs";
+    const { promises: fs } = await import(nodeFsModule);
+    const data = await fs.readFile(path);
+    const result = await this.createBlobFromData(new Uint8Array(data), {
+      ...opts
+    });
+    const fileName = path.split(/[\\/]/).pop() ?? path;
+    return { ...result, fileName };
+  }
+  /**
+   * One-shot custom-model publishing from raw GGUF weights, following the
+   * protocol Ollama's API reference documents: push a blob for the GGUF
+   * bytes, then `POST /api/create` with `files: { <fileName>: <digest> }`.
+   * Split GGUFs are supported via `files` — pass every shard's path.
+   *
+   * ```ts
+   * await client.models.createModelFromGguf('my-model', '/path/to/model.gguf', {
+   *   template: '{{ .Prompt }}',
+   * });
+   * ```
+   *
+   * @param model Name for the new model (e.g. `'my-model:latest'`).
+   * @param gguf Path(s) to GGUF file(s) on the local filesystem.
+   * @param opts Everything else `/api/create` accepts (`template`, `system`,
+   *   `parameters`, `license`, `quantize`, …) except `files` and `from`.
+   */
+  async createModelFromGguf(model, gguf, opts) {
+    const paths = typeof gguf === "string" ? [gguf] : gguf;
+    if (paths.length === 0) {
+      throw new OllamaClientError("createModelFromGguf: at least one GGUF path is required.", {
+        code: "invalid_request"
+      });
+    }
+    const files = {};
+    for (const path of paths) {
+      const uploaded = await this.createBlobFromFile(path, { signal: opts?.signal });
+      files[uploaded.fileName] = uploaded.digest;
+    }
+    const {
+      model: _model,
+      files: _files,
+      from: _from,
+      stream: _stream,
+      ...rest
+    } = opts ?? {};
+    return this.create({ ...rest, model, files, stream: false });
+  }
 };
 
 // src/integrations/openai.ts
@@ -1947,7 +2501,6 @@ var OpenAIChatCompletionStream = class {
       }
     }
   }
-  source;
   finalResultPromise;
   resolveFinal;
   rejectFinal;
@@ -2091,7 +2644,6 @@ var OpenAICompletionStream = class {
       }
     }
   }
-  source;
   finalResultPromise;
   resolveFinal;
   rejectFinal;
@@ -2172,7 +2724,6 @@ var OpenAIResponsesStream = class {
       }
     }
   }
-  source;
   finalResultPromise;
   resolveFinal;
   rejectFinal;
@@ -2397,8 +2948,6 @@ var OpenAICompatClient = class {
     this.http = http;
     this.runner = runner;
   }
-  http;
-  runner;
   request(operation, model, signal, holdUntil) {
     if (this.runner) {
       return this.runner(
@@ -2618,7 +3167,6 @@ var AnthropicMessagesStream = class {
       }
     }
   }
-  source;
   finalResultPromise;
   resolveFinal;
   rejectFinal;
@@ -2733,8 +3281,6 @@ var AnthropicCompatClient = class {
     this.http = http;
     this.runner = runner;
   }
-  http;
-  runner;
   request(operation, model, signal, holdUntil) {
     if (this.runner) {
       return this.runner(
@@ -2780,6 +3326,32 @@ var AnthropicCompatClient = class {
     return this.createMessage(request, signal);
   }
 };
+var IncludedBalanceSchema = zod.z.object({
+  balance_usd: zod.z.number(),
+  allowance_usd: zod.z.number(),
+  period: zod.z.object({
+    from: zod.z.string(),
+    until: zod.z.string()
+  })
+});
+var LegacyBalanceLimitSchema = zod.z.object({
+  remaining_percent: zod.z.number().min(0).max(100),
+  resets_at: zod.z.string()
+});
+
+// src/generated/models/LegacyIncludedBalance.schema.ts
+var LegacyIncludedBalanceSchema = zod.z.object({
+  session: LegacyBalanceLimitSchema,
+  weekly: LegacyBalanceLimitSchema
+});
+
+// src/generated/models/BalanceResponse.schema.ts
+var BalanceResponseSchema = zod.z.object({
+  included: zod.z.union([IncludedBalanceSchema, LegacyIncludedBalanceSchema]),
+  purchased: zod.z.object({
+    balance_usd: zod.z.number()
+  })
+});
 var ToolCallSchema = zod.z.object({
   function: zod.z.object({
     name: zod.z.string(),
@@ -2883,6 +3455,7 @@ var CreateRequestSchema = zod.z.object({
   quantize: zod.z.string().optional(),
   draft_quantize: zod.z.string().optional(),
   requires: zod.z.string().optional(),
+  capabilities: zod.z.array(zod.z.string()).optional(),
   stream: zod.z.boolean().optional()
 });
 var DeleteRequestSchema = zod.z.object({
@@ -2945,7 +3518,7 @@ var ModelSummarySchema = zod.z.object({
   details: zod.z.object({
     format: zod.z.string().optional(),
     family: zod.z.string().optional(),
-    families: zod.z.array(zod.z.string()).optional(),
+    families: zod.z.union([zod.z.array(zod.z.string()), zod.z.null()]).optional(),
     parameter_size: zod.z.string().optional(),
     quantization_level: zod.z.string().optional()
   }).optional()
@@ -3080,6 +3653,34 @@ var SystemOneResponseSchema = zod.z.object({
     output_tokens: zod.z.number().min(0)
   })
 });
+var UsageMetricsSchema = zod.z.object({
+  request_count: zod.z.number().min(0),
+  usage_usd: zod.z.number().optional(),
+  input_tokens: zod.z.number().optional(),
+  cached_input_tokens: zod.z.number().optional(),
+  output_tokens: zod.z.number().optional()
+});
+
+// src/generated/models/UsageBucket.schema.ts
+var UsageBucketSchema = zod.z.intersection(
+  UsageMetricsSchema,
+  zod.z.object({
+    from: zod.z.string(),
+    until: zod.z.string(),
+    partial: zod.z.boolean().optional()
+  })
+);
+
+// src/generated/models/UsageResponse.schema.ts
+var UsageResponseSchema = zod.z.object({
+  range: zod.z.enum(["24h", "7d", "30d"]),
+  scope: zod.z.enum(["self", "team"]),
+  granularity: zod.z.enum(["hour", "day"]),
+  from: zod.z.string(),
+  until: zod.z.string(),
+  totals: UsageMetricsSchema,
+  buckets: zod.z.array(UsageBucketSchema)
+});
 var VersionResponseSchema = zod.z.object({
   version: zod.z.string().optional()
 });
@@ -3122,6 +3723,7 @@ var requestSchemas = {
   webSearch: WebSearchRequestSchema
 };
 var responseSchemas = {
+  balance: BalanceResponseSchema,
   chat: ChatResponseSchema,
   create: StatusResponseSchema,
   embed: EmbedResponseSchema,
@@ -3132,6 +3734,7 @@ var responseSchemas = {
   show: ShowResponseSchema,
   systemOne: SystemOneResponseSchema,
   tags: ListResponseSchema,
+  usage: UsageResponseSchema,
   version: VersionResponseSchema,
   webFetch: WebFetchResponseSchema,
   webSearch: WebSearchResponseSchema
@@ -3182,7 +3785,6 @@ var OllamaRuntime = class {
   constructor(options) {
     this.options = options;
   }
-  options;
   /**
    * Cached promise of the Ollama server version, populated lazily the first
    * time a version-gated operation is invoked. `undefined` until then.
@@ -3259,11 +3861,19 @@ var OllamaRuntime = class {
     }
     const streaming = shouldStream(req);
     const resolvedPath = resolvePathParams(req.operation.path, req.pathParams);
+    const pathWithQuery = applyQueryParams(resolvedPath, req.queryParams);
     const model = req.model ?? extractModelFromBody(body);
+    const headers = {};
+    if (req.headerParams) {
+      for (const [key, value] of Object.entries(req.headerParams)) {
+        headers[key] = value;
+      }
+    }
     const httpReq = {
-      path: resolvedPath,
+      path: pathWithQuery,
       method: req.operation.method,
       ...body !== void 0 ? { body } : {},
+      ...Object.keys(headers).length > 0 ? { headers } : {},
       ...req.signal !== void 0 ? { signal: req.signal } : {},
       ...streaming ? { raw: true } : {},
       ...model !== void 0 ? { model } : {}
@@ -3404,6 +4014,589 @@ function extractModelFromBody(body) {
   const model = obj.model;
   return typeof model === "string" ? model : void 0;
 }
+function applyQueryParams(path, queryParams) {
+  if (!queryParams || Object.keys(queryParams).length === 0) return path;
+  const pairs = Object.entries(queryParams).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
+  return `${path}?${pairs}`;
+}
+
+// src/responses.ts
+var adapterResponseSequence = 0;
+function toNativeTools(tools) {
+  if (tools === void 0 || tools.length === 0) return void 0;
+  return tools.map((tool) => ({
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description ?? "",
+      parameters: tool.parameters ?? { type: "object", properties: {} }
+    }
+  }));
+}
+function mapNativeUsage(usage) {
+  if (usage === void 0) return void 0;
+  const input = usage.input_tokens ?? 0;
+  const output = usage.output_tokens ?? 0;
+  return { input_tokens: input, output_tokens: output, total_tokens: input + output };
+}
+function parseToolCallArguments(raw) {
+  if (raw === void 0 || raw === null || raw === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return { _raw: raw };
+  }
+}
+function mapNativeResponse(native) {
+  const textParts = [];
+  const thinkingParts = [];
+  const toolCalls = [];
+  for (const item of native.output ?? []) {
+    if (item.type === "message") {
+      for (const part of item.content ?? []) {
+        if (part.type === "output_text") textParts.push(part.text ?? "");
+        else if (part.type === "refusal") textParts.push(part.refusal ?? "");
+      }
+    } else if (item.type === "reasoning") {
+      if (item.text !== void 0 && item.text !== "") thinkingParts.push(item.text);
+    } else if (item.type === "function_call") {
+      toolCalls.push({
+        ...item.id !== void 0 ? { id: item.id } : {},
+        function: { name: item.name, arguments: parseToolCallArguments(item.arguments) }
+      });
+    }
+  }
+  return {
+    id: native.id ?? `resp_${Date.now().toString(36)}`,
+    model: native.model,
+    created_at: new Date((native.created_at ?? 0) * 1e3).toISOString(),
+    output_text: textParts.join(""),
+    ...thinkingParts.length > 0 ? { thinking: thinkingParts.join("\n") } : {},
+    ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {},
+    ...mapNativeUsage(native.usage) !== void 0 ? { usage: mapNativeUsage(native.usage) } : {}
+  };
+}
+function mapChatUsage(res) {
+  const asChat = res;
+  const asStream = res;
+  const input = asChat.prompt_eval_count ?? asStream.usage?.promptTokens ?? asStream.raw?.prompt_eval_count ?? 0;
+  const output = asChat.eval_count ?? asStream.usage?.completionTokens ?? asStream.raw?.eval_count ?? 0;
+  if (input === 0 && output === 0) return void 0;
+  return { input_tokens: input, output_tokens: output, total_tokens: input + output };
+}
+function mapChatResponse(res) {
+  adapterResponseSequence += 1;
+  return {
+    id: `resp_${Date.now().toString(36)}${adapterResponseSequence.toString(36)}`,
+    model: res.model,
+    created_at: res.created_at,
+    output_text: res.message.content,
+    ...res.message.thinking !== void 0 ? { thinking: res.message.thinking } : {},
+    ...res.message.tool_calls !== void 0 && res.message.tool_calls.length > 0 ? { tool_calls: res.message.tool_calls } : {},
+    ...mapChatUsage(res) !== void 0 ? { usage: mapChatUsage(res) } : {},
+    transport: "chat-adapter"
+  };
+}
+var ResponsesModule = class {
+  constructor(runner) {
+    this.runner = runner;
+  }
+  /** The request body sent to the native endpoint (also reused for streaming). */
+  nativeBody(req) {
+    return {
+      model: req.model,
+      input: req.input,
+      ...req.instructions !== void 0 ? { instructions: req.instructions } : {},
+      ...req.tools !== void 0 && req.tools.length > 0 ? { tools: toNativeTools(req.tools) } : {},
+      ...req.temperature !== void 0 ? { temperature: req.temperature } : {},
+      ...req.top_p !== void 0 ? { top_p: req.top_p } : {},
+      ...req.max_output_tokens !== void 0 ? { max_output_tokens: req.max_output_tokens } : {},
+      ...req.reasoning_effort !== void 0 ? { reasoning: { effort: req.reasoning_effort } } : {},
+      ...req.think !== void 0 ? { think: req.think } : {}
+    };
+  }
+  /**
+   * Runs one Responses request, preferring the native `POST /v1/responses`
+   * endpoint and transparently re-issuing via `/api/chat` when the server
+   * answers `404` (pre-v0.13.3 Ollama without the compatibility endpoint).
+   */
+  async create(req) {
+    const body = this.nativeBody(req);
+    try {
+      const native = await this.runner(
+        (http, signal) => http.request({
+          path: "/v1/responses",
+          body: { ...body, stream: false },
+          signal
+        }),
+        { model: req.model, signal: req.signal, timeoutMs: req.timeoutMs }
+      );
+      return { ...mapNativeResponse(native), transport: "native" };
+    } catch (err) {
+      if (!(err instanceof OllamaNotFoundError)) throw err;
+    }
+    return this.createViaChatAdapter(req);
+  }
+  /** Convenience: `create()` returning only the `output_text` string. */
+  async createText(req) {
+    const res = await this.create(req);
+    return res.output_text;
+  }
+  async createViaChatAdapter(req) {
+    const messages = [
+      ...req.instructions !== void 0 ? [{ role: "system", content: req.instructions }] : [],
+      { role: "user", content: req.input }
+    ];
+    const chatRes = await this.runner(
+      (http, signal) => http.request({
+        path: "/api/chat",
+        body: {
+          model: req.model,
+          messages,
+          ...req.tools !== void 0 && req.tools.length > 0 ? { tools: toNativeTools(req.tools) } : {},
+          options: {
+            ...req.temperature !== void 0 ? { temperature: req.temperature } : {},
+            ...req.top_p !== void 0 ? { top_p: req.top_p } : {},
+            ...req.max_output_tokens !== void 0 ? { num_predict: req.max_output_tokens } : {}
+          },
+          ...req.think !== void 0 ? { think: req.think } : {},
+          stream: false
+        },
+        signal
+      }),
+      { model: req.model, signal: req.signal, timeoutMs: req.timeoutMs }
+    );
+    return mapChatResponse(chatRes);
+  }
+  /**
+   * Streams a Responses request as simplified
+   * `{type: 'text_delta' | 'thinking_delta' | 'done'}` events. Dual-mode like
+   * {@link create}: native SSE from `/v1/responses` when available, otherwise
+   * the normalized `/api/chat` token stream. Tool calls are not delta'd —
+   * collect them from the final `done` event's `response.tool_calls`.
+   *
+   * This is a lazy async generator: nothing is sent until the first
+   * iteration, matching `for await (... of client.responses.stream(req))`
+   * intuition. The generator is also cancellable through `req.signal`.
+   */
+  async *stream(req) {
+    const body = this.nativeBody(req);
+    let nativeStream;
+    try {
+      nativeStream = await this.runner(
+        async (http, signal) => {
+          const source = await http.requestSseStream({
+            path: "/v1/responses",
+            body: { ...body, stream: true },
+            signal
+          });
+          return new OpenAIResponsesStream(source, signal);
+        },
+        {
+          model: req.model,
+          signal: req.signal,
+          timeoutMs: req.timeoutMs,
+          holdUntil: (s) => s.finalResult
+        }
+      );
+    } catch (err) {
+      if (!(err instanceof OllamaNotFoundError)) throw err;
+    }
+    if (nativeStream !== void 0) {
+      for await (const event of nativeStream) {
+        const type = event.type;
+        if (type === "response.output_text.delta") {
+          yield { type: "text_delta", delta: event.delta };
+        } else if (type === "response.reasoning_text.delta") {
+          yield { type: "thinking_delta", delta: event.delta };
+        }
+      }
+      yield {
+        type: "done",
+        response: { ...mapNativeResponse(await nativeStream.finalResult), transport: "native" }
+      };
+      return;
+    }
+    const chatStream = await this.runner(
+      async (http, signal) => {
+        const source = await http.requestStream({
+          path: "/api/chat",
+          body: {
+            model: req.model,
+            messages: [
+              ...req.instructions !== void 0 ? [{ role: "system", content: req.instructions }] : [],
+              { role: "user", content: req.input }
+            ],
+            ...req.tools !== void 0 && req.tools.length > 0 ? { tools: toNativeTools(req.tools) } : {},
+            options: {
+              ...req.temperature !== void 0 ? { temperature: req.temperature } : {},
+              ...req.top_p !== void 0 ? { top_p: req.top_p } : {},
+              ...req.max_output_tokens !== void 0 ? { num_predict: req.max_output_tokens } : {}
+            },
+            ...req.think !== void 0 ? { think: req.think } : {},
+            stream: true
+          },
+          signal
+        });
+        return normalizeChatStream(source, signal);
+      },
+      {
+        model: req.model,
+        signal: req.signal,
+        timeoutMs: req.timeoutMs,
+        holdUntil: (s) => s.finalResult
+      }
+    );
+    for await (const event of chatStream) {
+      if (event.type === "token") {
+        yield { type: "text_delta", delta: event.data.delta };
+      } else if (event.type === "thinking") {
+        yield { type: "thinking_delta", delta: event.data.delta };
+      }
+    }
+    const result = await chatStream.finalResult;
+    yield {
+      type: "done",
+      response: {
+        id: `resp_${Date.now().toString(36)}${(++adapterResponseSequence).toString(36)}`,
+        model: result.model,
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        output_text: result.message.content,
+        ...result.message.thinking !== void 0 ? { thinking: result.message.thinking } : {},
+        ...result.message.tool_calls !== void 0 && result.message.tool_calls.length > 0 ? { tool_calls: result.message.tool_calls } : {},
+        ...mapChatUsage(result) !== void 0 ? { usage: mapChatUsage(result) } : {},
+        transport: "chat-adapter"
+      }
+    };
+  }
+};
+
+// src/conversation.ts
+function extractTurnStats(res) {
+  const cachedTokens = res.prompt_eval_cached_count ?? 0;
+  const evaluatedTokens = res.prompt_eval_count ?? 0;
+  const total = cachedTokens + evaluatedTokens;
+  return {
+    cachedTokens,
+    evaluatedTokens,
+    hitRate: total > 0 ? cachedTokens / total : 0
+  };
+}
+var ConversationSession = class {
+  constructor(client, config) {
+    this.client = client;
+    this.config = config;
+    if (config.systemPrompt !== void 0 && config.systemPrompt !== "") {
+      this.history.push(Object.freeze({ role: "system", content: config.systemPrompt }));
+    }
+  }
+  /** Ordered, append-only history. Message objects are frozen on push. */
+  history = [];
+  /** Mutable tallies behind the read-only {@link cacheStats} view. */
+  tallies = {
+    turns: 0,
+    cachedTokens: 0,
+    evaluatedTokens: 0
+  };
+  /** The model name this session talks to. */
+  get model() {
+    return this.config.model;
+  }
+  /** Number of completed turns. */
+  get turnCount() {
+    return this.tallies.turns;
+  }
+  /** Cumulative KV-cache statistics across completed turns. */
+  get cacheStats() {
+    const total = this.tallies.cachedTokens + this.tallies.evaluatedTokens;
+    return {
+      turns: this.tallies.turns,
+      cachedTokens: this.tallies.cachedTokens,
+      evaluatedTokens: this.tallies.evaluatedTokens,
+      totalPromptTokens: total,
+      hitRate: total > 0 ? this.tallies.cachedTokens / total : 0
+    };
+  }
+  /**
+   * Sends the user's message and returns the assistant's reply text —
+   * the ergonomic path. Use {@link sendTurn} when you also need the
+   * per-turn cache statistics or the raw response.
+   */
+  async send(content, overrides) {
+    const turn = await this.sendTurn(content, overrides);
+    return turn.content;
+  }
+  /**
+   * Sends the user's message and returns the full turn record: reply text,
+   * per-turn KV-cache statistics, and the raw `/api/chat` response.
+   */
+  async sendTurn(content, overrides) {
+    this.history.push(Object.freeze({ role: "user", content }));
+    const response = await this.client.chat({
+      model: this.config.model,
+      messages: [...this.history],
+      ...this.config.tools !== void 0 || overrides?.tools !== void 0 ? { tools: overrides?.tools ?? this.config.tools } : {},
+      ...this.config.format !== void 0 || overrides?.format !== void 0 ? { format: overrides?.format ?? this.config.format } : {},
+      options: { ...this.config.options, ...overrides?.options },
+      ...this.config.think !== void 0 || overrides?.think !== void 0 ? { think: overrides?.think ?? this.config.think } : {},
+      ...this.config.keep_alive !== void 0 || overrides?.keep_alive !== void 0 ? { keep_alive: overrides?.keep_alive ?? this.config.keep_alive } : {},
+      ...overrides?.signal !== void 0 ? { signal: overrides.signal } : {},
+      ...overrides?.timeoutMs !== void 0 ? { timeoutMs: overrides.timeoutMs } : {},
+      stream: false
+    });
+    this.history.push(Object.freeze({ ...response.message }));
+    const cache = extractTurnStats(response);
+    this.tallies.turns += 1;
+    this.tallies.cachedTokens += cache.cachedTokens;
+    this.tallies.evaluatedTokens += cache.evaluatedTokens;
+    return { content: response.message.content, cache, response };
+  }
+  /**
+   * A defensive copy of the session history — mutating the returned array or
+   * its frozen messages has no effect on the session.
+   */
+  getMessages() {
+    return this.history.map((message) => message);
+  }
+  /**
+   * Clears the conversation back to its initial state (system prompt, zero
+   * turns, zeroed cache statistics). The next turn starts with a cold cache
+   * by definition — there is nothing upstream of it to reuse.
+   */
+  reset() {
+    this.history.length = 0;
+    if (this.config.systemPrompt !== void 0 && this.config.systemPrompt !== "") {
+      this.history.push(
+        Object.freeze({ role: "system", content: this.config.systemPrompt })
+      );
+    }
+    this.tallies.turns = 0;
+    this.tallies.cachedTokens = 0;
+    this.tallies.evaluatedTokens = 0;
+  }
+};
+
+// 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/embed-batch.ts
+var DEFAULT_EMBED_BATCH_SIZE = 32;
+var DEFAULT_EMBED_CONCURRENCY = 3;
+function findOversizedEmbedInputs(input, contextLength) {
+  const oversized = [];
+  for (let index = 0; index < input.length; index++) {
+    const text = input[index];
+    if (text === void 0) continue;
+    const estimate = estimateTokens(text);
+    if (estimate > contextLength) {
+      oversized.push({ index, estimate });
+    }
+  }
+  return oversized;
+}
+function embedBatchOverflowMessage(oversized, totalInputs, contextLength, truncateFalse) {
+  const shown = oversized.slice(0, 5).map((entry) => `#${entry.index} (~${entry.estimate} tokens)`);
+  const elided = oversized.length > 5 ? `, +${oversized.length - 5} more` : "";
+  const outcome = truncateFalse ? "the server will reject them (`truncate: false`)" : "Ollama will silently truncate them, producing degraded vectors";
+  return `embedBatch: ${oversized.length} of ${totalInputs} input strings exceed the ${contextLength}-token context window (${shown.join(", ")}${elided}). ${outcome}. Raise \`options.num_ctx\`, pre-split long inputs, or set \`truncate: true\` explicitly to acknowledge truncation.`;
+}
+function assertPositiveInteger(value, field) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new OllamaClientError(
+      `embedBatch: \`${field}\` must be a positive integer (got ${value}).`,
+      { code: "invalid_request" }
+    );
+  }
+}
+async function batchEmbed(client, options) {
+  const { model, input } = options;
+  const batchSize = options.batchSize ?? DEFAULT_EMBED_BATCH_SIZE;
+  const concurrency = options.concurrency ?? DEFAULT_EMBED_CONCURRENCY;
+  assertPositiveInteger(batchSize, "batchSize");
+  assertPositiveInteger(concurrency, "concurrency");
+  if (input.length === 0) {
+    return { model, embeddings: [], batchCount: 0 };
+  }
+  const batches = [];
+  for (let start = 0; start < input.length; start += batchSize) {
+    batches.push(input.slice(start, start + batchSize));
+  }
+  const embeddings = new Array(input.length);
+  const controller = new AbortController();
+  const propagateExternalAbort = () => {
+    controller.abort(options.signal?.reason);
+  };
+  if (options.signal) {
+    if (options.signal.aborted) {
+      propagateExternalAbort();
+    } else {
+      options.signal.addEventListener("abort", propagateExternalAbort, { once: true });
+    }
+  }
+  let nextBatch = 0;
+  let completedBatches = 0;
+  let failure;
+  const worker = async () => {
+    for (; ; ) {
+      if (controller.signal.aborted) {
+        throw failure?.error ?? new OllamaAbortError("Embed batch aborted");
+      }
+      const batchIndex = nextBatch;
+      nextBatch++;
+      if (batchIndex >= batches.length) return;
+      const batch = batches[batchIndex];
+      if (!batch) return;
+      try {
+        const request = {
+          model,
+          input: batch,
+          ...options.truncate !== void 0 ? { truncate: options.truncate } : {},
+          ...options.dimensions !== void 0 ? { dimensions: options.dimensions } : {},
+          ...options.keep_alive !== void 0 ? { keep_alive: options.keep_alive } : {},
+          ...options.options !== void 0 ? { options: options.options } : {},
+          ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {},
+          signal: controller.signal
+        };
+        const response = await client.embed(request);
+        if (response.embeddings.length !== batch.length) {
+          throw new OllamaClientError(
+            `embedBatch: server returned ${response.embeddings.length} embeddings for a batch of ${batch.length} inputs (batch ${batchIndex}).`,
+            { code: "invalid_response" }
+          );
+        }
+        const offset = batchIndex * batchSize;
+        for (let j = 0; j < batch.length; j++) {
+          embeddings[offset + j] = response.embeddings[j];
+        }
+        completedBatches++;
+        options.onBatchComplete?.(completedBatches, batches.length);
+      } catch (error) {
+        if (!failure) {
+          failure = { error };
+          controller.abort(error);
+          throw error;
+        }
+        throw failure.error;
+      }
+    }
+  };
+  try {
+    const workerCount = Math.min(concurrency, batches.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  } finally {
+    if (options.signal) {
+      options.signal.removeEventListener("abort", propagateExternalAbort);
+    }
+  }
+  for (let i = 0; i < embeddings.length; i++) {
+    if (embeddings[i] === void 0) {
+      throw new OllamaClientError(
+        `embedBatch: internal invariant violated \u2014 no embedding produced for input #${i}.`,
+        { code: "invalid_response" }
+      );
+    }
+  }
+  return {
+    model,
+    embeddings,
+    batchCount: batches.length
+  };
+}
 
 // src/generated/api/operations.ts
 var blobsOp = {
@@ -3615,7 +4808,6 @@ var NativeApi = class {
   constructor(runtime) {
     this.runtime = runtime;
   }
-  runtime;
   blobs(digest, options) {
     return this.runtime.invoke({
       operation: blobsOp,
@@ -3718,7 +4910,6 @@ var FailoverHttpClient = class {
     this.client = client;
     this.baseUrl = baseUrl;
   }
-  client;
   /**
    * The first candidate endpoint's base URL. Used for inferRuntimeMode()
    * checks (local vs cloud). The actual request routing picks the best
@@ -3925,14 +5116,29 @@ var OllamaClient = class {
    * `OLLAMA_API_KEY`), independent of whether `config.endpoints` was used instead.
    */
   cloudApiKey;
+  /** Configured `defaultContextLength` — injected as `num_ctx` when a request omits it. */
+  defaultContextLength;
+  /** Configured `contextWarningThreshold` (default 0.9). */
+  contextWarningThreshold;
+  /** Configured overflow policy — `'warn'` (default) or `'throw'`. */
+  onContextOverflow;
+  /**
+   * Controllers for every in-flight request and active stream managed by this
+   * client — see {@link OllamaClient.destroy} and {@link createRequestScope}.
+   * Entries live for exactly as long as the underlying work does: until the
+   * response settles (requests) or the stream's `finalResult` settles
+   * (streams, via `executeWithFailover`'s `holdUntil` release path).
+   */
+  activeRequests = /* @__PURE__ */ new Set();
   constructor(config = {}) {
-    const resolvedApiKey = resolveApiKey(config.apiKey);
-    this.cloudApiKey = resolvedApiKey;
+    this.cloudApiKey = resolveApiKey(config.apiKey);
+    const defaultBaseUrl = resolveBaseUrl(config.baseUrl);
+    const resolvedApiKey = resolveEndpointApiKey(config.apiKey, defaultBaseUrl);
     const credentialEndpoints = resolveCredentialEndpoints(config);
     const endpoints = config.endpoints ?? (credentialEndpoints.length > 0 ? [] : [
       {
         name: "default",
-        baseUrl: resolveBaseUrl(config.baseUrl),
+        baseUrl: defaultBaseUrl,
         ...resolvedApiKey !== void 0 ? { apiKey: resolvedApiKey } : {},
         ...config.headers !== void 0 ? { headers: config.headers } : {}
       }
@@ -3948,6 +5154,9 @@ var OllamaClient = class {
     this.middleware = config.middleware;
     this.onLifecycleEvent = config.onLifecycleEvent;
     this.retryConfig = typeof config.retries === "number" ? { ...DEFAULT_RETRY_CONFIG, maxRetries: config.retries } : { ...DEFAULT_RETRY_CONFIG, ...config.retries };
+    this.defaultContextLength = config.defaultContextLength;
+    this.contextWarningThreshold = config.contextWarningThreshold;
+    this.onContextOverflow = config.onContextOverflow ?? "warn";
     this.models = new ModelsClient((op, opts) => this.executeWithFailover(op, opts));
   }
   get modelsClient() {
@@ -4037,6 +5246,87 @@ var OllamaClient = class {
     return this._decision;
   }
   _decision;
+  /**
+   * Ergonomic OpenAI Responses API bridge (`client.responses.create()` /
+   * `.stream()`). Dual-mode transport: prefers the native `POST
+   * /v1/responses` endpoint (Ollama ≥ v0.13.3) and transparently re-issues via
+   * `/api/chat` when the server answers 404, so migrating OpenAI code works
+   * unchanged against older servers. See `src/responses.ts`.
+   */
+  get responses() {
+    if (this._responses === void 0) {
+      this._responses = new ResponsesModule((op, opts) => this.executeWithFailover(op, opts));
+    }
+    return this._responses;
+  }
+  _responses;
+  session(modelOrOptions, systemPrompt) {
+    const options = typeof modelOrOptions === "string" ? {
+      model: modelOrOptions,
+      ...systemPrompt !== void 0 ? { systemPrompt } : {}
+    } : modelOrOptions;
+    return new ConversationSession(this, options);
+  }
+  /**
+   * Context-window pre-flight enforcement — see `src/context-safety.ts` and
+   * the `defaultContextLength` / `onContextOverflow` config docs. Logs a
+   * warning (default) or throws client-side when the estimated prompt size
+   * is close to / beyond the effective context window.
+   */
+  enforceContextSafety(kind, check2) {
+    if (!check2.exceedsThreshold) return;
+    const message = contextWarningMessage(check2, kind);
+    if (this.onContextOverflow === "throw") {
+      throw new OllamaClientError(message, { code: "context_overflow" });
+    }
+    this.logger.warn(message);
+  }
+  /**
+   * Returns `options` with `num_ctx` injected from the client's
+   * `defaultContextLength` when the request didn't set one — making the
+   * effective context window explicit on the wire instead of relying on
+   * Ollama's silently-truncating server default. Returns the original
+   * reference when there's nothing to inject (the common case).
+   */
+  injectDefaultContextLength(options) {
+    if (options?.num_ctx !== void 0 || this.defaultContextLength === void 0) {
+      return options;
+    }
+    return { ...options, num_ctx: this.defaultContextLength };
+  }
+  /**
+   * Creates the per-request abort scope registered with {@link destroy}:
+   * a controller that fires when the caller's `signal` aborts OR when
+   * `destroy()` runs, whichever comes first. `dispose()` removes the
+   * registration when the work it guards settles — for plain requests when
+   * the response settles, for streams when `finalResult` settles (the same
+   * moment `executeWithFailover`'s `holdUntil` releases the endpoint slot),
+   * so a destroy() can tear down a stream mid-consumption but never outlives
+   * one that already finished.
+   */
+  createRequestScope(userSignal) {
+    const controller = new AbortController();
+    const propagateUserAbort = () => {
+      controller.abort(userSignal?.reason);
+    };
+    let detach;
+    if (userSignal) {
+      if (userSignal.aborted) {
+        propagateUserAbort();
+      } else {
+        userSignal.addEventListener("abort", propagateUserAbort, { once: true });
+        detach = () => userSignal.removeEventListener("abort", propagateUserAbort);
+      }
+    }
+    this.activeRequests.add(controller);
+    return {
+      signal: controller.signal,
+      dispose: () => {
+        detach?.();
+        this.activeRequests.delete(controller);
+      }
+    };
+  }
   /**
    * Fail-fast guard for `format` (structured output) requests: throws before any network
    * call if the candidate endpoint is inferred as Ollama Cloud, which does not currently
@@ -4053,7 +5343,8 @@ var OllamaClient = class {
     }
   }
   async executeWithFailover(operation, options) {
-    const timeout = createTimeoutSignal(options?.timeoutMs ?? this.timeoutMs, options?.signal);
+    const scope = this.createRequestScope(options?.signal);
+    const timeout = createTimeoutSignal(options?.timeoutMs ?? this.timeoutMs, scope.signal);
     const requestId = createLogicalRequestId();
     let deferTimeoutCancel = false;
     try {
@@ -4132,6 +5423,7 @@ var OllamaClient = class {
             if (holdPromise) {
               void holdPromise.catch(() => void 0).finally(() => {
                 timeout.cancel();
+                scope.dispose();
                 this.registry.release(endpoint.name);
               });
             } else {
@@ -4142,11 +5434,14 @@ var OllamaClient = class {
         throw lastError ?? new Error("No healthy Ollama endpoints available");
       }
     } finally {
-      if (!deferTimeoutCancel) timeout.cancel();
+      if (!deferTimeoutCancel) {
+        timeout.cancel();
+        scope.dispose();
+      }
     }
   }
   async chat(req) {
-    const encodedMessages = await withEncodedMessageImages(req.messages);
+    const encodedMessages = await withEncodedMessageImages(req.messages, req.signal);
     const messages = encodedMessages.map((message) => {
       if (message.role === "tool" && message.tool_call_id !== void 0) {
         const { tool_call_id: _toolCallId, ...nativeMessage } = message;
@@ -4154,6 +5449,14 @@ var OllamaClient = class {
       }
       return message;
     });
+    this.enforceContextSafety(
+      "chat",
+      checkChatContext(req, {
+        defaultContextLength: this.defaultContextLength,
+        threshold: this.contextWarningThreshold
+      })
+    );
+    const options = this.injectDefaultContextLength(req.options);
     if (req.stream) {
       return this.executeWithFailover(
         async (http, signal) => {
@@ -4161,7 +5464,7 @@ var OllamaClient = class {
             this.assertStructuredOutputSupported(http.baseUrl, req.model);
           const stream = await http.requestStream({
             path: "/api/chat",
-            body: { ...req, messages, stream: true },
+            body: { ...req, options, messages, stream: true },
             signal
           });
           return normalizeChatStream(stream, signal);
@@ -4190,7 +5493,7 @@ var OllamaClient = class {
             this.assertStructuredOutputSupported(http.baseUrl, req.model);
           return http.request({
             path: "/api/chat",
-            body: { ...req, messages, stream: false },
+            body: { ...req, options, messages, stream: false },
             signal
           });
         }, req);
@@ -4217,7 +5520,15 @@ var OllamaClient = class {
     return parseStructuredOutput(res.message.content, schema);
   }
   async generate(req) {
-    const encodedReq = await withEncodedImages(req);
+    const encodedReq = await withEncodedImages(req, req.signal);
+    this.enforceContextSafety(
+      "generate",
+      checkGenerateContext(req, {
+        defaultContextLength: this.defaultContextLength,
+        threshold: this.contextWarningThreshold
+      })
+    );
+    const options = this.injectDefaultContextLength(req.options);
     if (encodedReq.stream) {
       return this.executeWithFailover(
         async (http, signal) => {
@@ -4225,7 +5536,7 @@ var OllamaClient = class {
             this.assertStructuredOutputSupported(http.baseUrl, encodedReq.model);
           const stream = await http.requestStream({
             path: "/api/generate",
-            body: { ...encodedReq, stream: true },
+            body: { ...encodedReq, options, stream: true },
             signal
           });
           return normalizeGenerateStream(stream, signal);
@@ -4251,7 +5562,7 @@ var OllamaClient = class {
             this.assertStructuredOutputSupported(http.baseUrl, encodedReq.model);
           return http.request({
             path: "/api/generate",
-            body: { ...encodedReq, stream: false },
+            body: { ...encodedReq, options, stream: false },
             signal
           });
         }, encodedReq);
@@ -4286,6 +5597,58 @@ var OllamaClient = class {
     const res = await this.embed({ model, input });
     return res.embeddings;
   }
+  /**
+   * Batch-constrained, order-preserving embedding generation for large
+   * corpora — the safe building block for RAG/vector-index ingestion at
+   * scale. Splits `input` into `batchSize` slices and embeds them through
+   * {@link embed} with at most `concurrency` batches in flight (defaults:
+   * 32 × 3), so `Promise.all`-style floods that OOM local daemons and
+   * saturate `OLLAMA_MAX_QUEUE` can't happen by accident. Fail-fast: the
+   * first batch error aborts every sibling in-flight batch and rejects the
+   * whole operation with the original error.
+   *
+   * Before any request is sent, `defaultContextLength` is injected as
+   * `num_ctx` (same as chat/generate) and each input string's token estimate
+   * is checked against the resolved window: Ollama silently truncates
+   * oversized embedding inputs by default, so the client warns (or throws,
+   * under `onContextOverflow: 'throw'`) with the offending indexes — see
+   * `src/embed-batch.ts` for the exact trip point (no margin: an embedding
+   * prompt IS the whole input).
+   *
+   * ```ts
+   * const { embeddings, batchCount } = await client.embedBatch({
+   *   model: 'nomic-embed-text:latest',
+   *   input: corpus,                 // e.g. 50k chunks
+   *   batchSize: 32,                 // inputs per /api/embed request
+   *   concurrency: 3,                // batches in flight
+   *   onBatchComplete: (done, total) => progress.log(`${done}/${total}`),
+   * });
+   * // embeddings[i] always corresponds to corpus[i]
+   * ```
+   */
+  async embedBatch(options) {
+    const resolvedOptions = this.injectDefaultContextLength(options.options);
+    const contextLength = resolvedOptions?.num_ctx;
+    if (contextLength !== void 0) {
+      const oversized = findOversizedEmbedInputs(options.input, contextLength);
+      if (oversized.length > 0) {
+        const message = embedBatchOverflowMessage(
+          oversized,
+          options.input.length,
+          contextLength,
+          options.truncate === false
+        );
+        if (this.onContextOverflow === "throw") {
+          throw new OllamaClientError(message, { code: "context_overflow" });
+        }
+        this.logger.warn(message);
+      }
+    }
+    return batchEmbed(
+      this,
+      resolvedOptions === options.options ? options : { ...options, options: resolvedOptions }
+    );
+  }
   /**
    * @deprecated Ollama's `/api/embeddings` endpoint has been superseded by `/api/embed`
    * (exposed here as {@link OllamaClient.embed}), which additionally supports batch
@@ -4309,6 +5672,18 @@ var OllamaClient = class {
   version = () => this.models.version();
   createBlob = (digest, data) => this.models.createBlob(digest, data);
   checkBlob = (digest) => this.models.checkBlob(digest);
+  /**
+   * Immediately unloads `model` from VRAM. Convenience alias for
+   * {@link ModelsClient.unload} — see that method for the full
+   * lifecycle contract.
+   */
+  unloadModel = (model) => this.models.unload(model);
+  /**
+   * Pre-loads and pins `model` into VRAM indefinitely. Convenience
+   * alias for {@link ModelsClient.pin} — see that method for the
+   * full lifecycle contract.
+   */
+  pinModel = (model) => this.models.pin(model);
   // --- System One (Wave 13) ---
   /**
    * Ollama's System One decision layer (`POST /v1/systemone`) — evaluates
@@ -4378,6 +5753,63 @@ var OllamaClient = class {
       req
     );
   }
+  /**
+   * Ollama Cloud usage statistics (`GET https://ollama.com/api/usage`) — request counts,
+   * USD spend, and token totals (including cached input tokens) for cloud inference,
+   * web search, and web fetch, bucketed by hour (`range: '24h'`) or day (`'7d'`/`'30d'`).
+   *
+   * See {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry
+   * behavior, which applies identically here. Query parameters mirror the official
+   * endpoint: `range` (`'24h' | '7d' | '30d'`, server default `'7d'`) and `scope`
+   * (`'self' | 'team'`, server default `'self'`; team scope requires a team admin).
+   * Omitted options are left unset so the server applies its own defaults.
+   *
+   * ```ts
+   * const usage = await client.usage({ range: '24h' });
+   * console.log(usage.totals.request_count, usage.totals.usage_usd);
+   * for (const bucket of usage.buckets) {
+   *   if (bucket.partial) continue; // current hour, still in progress
+   *   // ...
+   * }
+   * ```
+   */
+  usage(req = {}) {
+    const params = new URLSearchParams();
+    if (req.range !== void 0) params.set("range", req.range);
+    if (req.scope !== void 0) params.set("scope", req.scope);
+    const query = params.toString();
+    return this.executeCloudRequest(
+      (http, signal) => http.request({
+        path: query ? `/api/usage?${query}` : "/api/usage",
+        method: "GET",
+        signal
+      }),
+      req
+    );
+  }
+  /**
+   * Ollama Cloud balance (`GET https://ollama.com/api/balance`) — remaining included
+   * and purchased usage credits. The included balance is either a plan-period credit
+   * object (`balance_usd`/`allowance_usd`/`period`) or, on legacy plans, session/weekly
+   * percentage limits; the shape is discriminated at runtime by the server response.
+   * See {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry
+   * behavior, which applies identically here.
+   *
+   * ```ts
+   * const balance = await client.balance();
+   * if ('balance_usd' in balance.included) {
+   *   console.log(balance.included.balance_usd, balance.purchased.balance_usd);
+   * } else {
+   *   console.log(balance.included.session.remaining_percent, '% of session limit left');
+   * }
+   * ```
+   */
+  balance(req = {}) {
+    return this.executeCloudRequest(
+      (http, signal) => http.request({ path: "/api/balance", method: "GET", 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
@@ -4386,10 +5818,12 @@ var OllamaClient = class {
   async executeCloudRequest(operation, options) {
     var _stack = [];
     try {
-      const timeout = createTimeoutSignal(options.timeoutMs ?? this.timeoutMs, options.signal);
+      const scope = this.createRequestScope(options.signal);
+      const timeout = createTimeoutSignal(options.timeoutMs ?? this.timeoutMs, scope.signal);
       const _timeout = __using(_stack, {
         [Symbol.dispose]() {
           timeout.cancel();
+          scope.dispose();
         }
       });
       const requestId = createLogicalRequestId();
@@ -4450,6 +5884,34 @@ var OllamaClient = class {
   endpointStatus() {
     return this.registry.status();
   }
+  /**
+   * Immediately aborts every in-flight request and active stream managed by
+   * this client — the clean teardown path for short-lived processes, CLI
+   * runners, and `node:worker_threads` tasks where dangling fetch bodies,
+   * unconsumed stream readers, or queued capacity waiters would otherwise
+   * keep the event loop (and thus the thread/process) alive.
+   *
+   * Every aborted operation rejects with an {@link OllamaAbortError}
+   * (`code: 'aborted'`) carrying `reason` as its message — including requests
+   * still queued behind `maxConcurrentPerEndpoint`, not just dispatched ones.
+   * Streams reject their `finalResult` and release their endpoint slots.
+   *
+   * Idempotent: calling it again (or on a client with nothing in flight)
+   * is a no-op that returns `0`. The client remains usable afterward —
+   * `destroy()` is a drain, not a permanent disable; callers that want a
+   * permanently-dead client should discard the instance.
+   *
+   * @returns the number of in-flight operations that were aborted.
+   */
+  destroy(reason = "Ollama client destroyed") {
+    const controllers = [...this.activeRequests];
+    const cause = new OllamaAbortError(reason);
+    for (const controller of controllers) {
+      controller.abort(cause);
+    }
+    this.activeRequests.clear();
+    return controllers.length;
+  }
   // --- Compatibility Adapters ---
   get openai() {
     const ep = this.registry.candidates()[0];
@@ -4481,6 +5943,91 @@ var OllamaClient = class {
   }
 };
 
+// src/transport/fetch-with-backoff.ts
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 503]);
+var DEFAULT_FETCH_BACKOFF_CONFIG = {
+  maxRetries: 3
+};
+function sleep2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(
+        Object.assign(new Error("fetchWithBackoff aborted during backoff sleep"), {
+          name: "AbortError"
+        })
+      );
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(
+        Object.assign(new Error("fetchWithBackoff aborted during backoff sleep"), {
+          name: "AbortError"
+        })
+      );
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function fetchWithBackoff(input, init, config = {}) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error(
+      "fetchWithBackoff: no global fetch is available. Pass a fetch implementation via config.fetch, or run in Node.js >= 18 / a browser-like environment."
+    );
+  }
+  const maxRetries = config.maxRetries ?? DEFAULT_FETCH_BACKOFF_CONFIG.maxRetries;
+  const backoff = config.backoff ?? DEFAULT_BACKOFF;
+  const signal = config.signal;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    if (signal?.aborted) {
+      throw Object.assign(new Error("fetchWithBackoff aborted"), { name: "AbortError" });
+    }
+    try {
+      const response = await fetchImpl(input, {
+        ...init,
+        ...signal !== void 0 ? { signal } : {}
+      });
+      if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < maxRetries) {
+        const delayMs = calculateBackoff(attempt, backoff);
+        config.onRetry?.(attempt, response.status, delayMs);
+        await sleep2(delayMs, signal);
+        continue;
+      }
+      return response;
+    } catch (err) {
+      lastError = err;
+      if (signal?.aborted || err instanceof Error && err.name === "AbortError") {
+        throw err;
+      }
+      if (attempt < maxRetries) {
+        const delayMs = calculateBackoff(attempt, backoff);
+        config.onRetry?.(attempt, 0, delayMs);
+        await sleep2(delayMs, signal);
+        continue;
+      }
+    }
+  }
+  throw lastError ?? new Error("fetchWithBackoff: exhausted retry attempts");
+}
+
+// src/done-reason.ts
+var KNOWN_DONE_REASONS = /* @__PURE__ */ new Set([
+  "stop",
+  "length",
+  "load",
+  "unload"
+]);
+function isKnownDoneReason(value) {
+  return value !== void 0 && value !== null && KNOWN_DONE_REASONS.has(value);
+}
+
 // src/streaming/adapters.ts
 function toTextStream(stream) {
   const iterator = stream[Symbol.asyncIterator]();
@@ -4936,9 +6483,9 @@ function validate(value, schema, path) {
       ["exclusiveMinimum", (n, b) => n > b, "must be greater than"],
       ["exclusiveMaximum", (n, b) => n < b, "must be less than"]
     ];
-    for (const [keyword, check, phrase] of numericRules) {
+    for (const [keyword, check2, phrase] of numericRules) {
       const bound = s[keyword];
-      if (typeof bound === "number" && !check(value, bound)) issues.push({ path, message: label(path) + " " + phrase + " " + bound });
+      if (typeof bound === "number" && !check2(value, bound)) issues.push({ path, message: label(path) + " " + phrase + " " + bound });
     }
     const multipleOf = s["multipleOf"];
     if (typeof multipleOf === "number" && multipleOf > 0) {
@@ -5199,8 +6746,6 @@ var McpBridge = class _McpBridge {
     this.client = client;
     this.options = options;
   }
-  client;
-  options;
   static toOllamaTools(tools, options = {}) {
     const prefix = options.namePrefix ?? "";
     return tools.map((tool) => ({
@@ -5497,6 +7042,13 @@ var Agent = class {
   }
 };
 
+// src/system-one.ts
+var MAX_SYSTEM_ONE_IMAGES_BYTES = 32 * 1024 * 1024;
+var MAX_SYSTEM_ONE_REQUEST_BYTES = 64 * 1024;
+function estimateSystemOneRequestBytes(request) {
+  return new TextEncoder().encode(JSON.stringify(request)).byteLength;
+}
+
 exports.ATTR_GEN_AI_OPERATION_NAME = ATTR_GEN_AI_OPERATION_NAME;
 exports.ATTR_GEN_AI_REQUEST_MODEL = ATTR_GEN_AI_REQUEST_MODEL;
 exports.ATTR_GEN_AI_RESPONSE_MODEL = ATTR_GEN_AI_RESPONSE_MODEL;
@@ -5517,24 +7069,37 @@ exports.ATTR_URL_FULL = ATTR_URL_FULL;
 exports.Agent = Agent;
 exports.AnthropicCompatClient = AnthropicCompatClient;
 exports.AnthropicMessagesStream = AnthropicMessagesStream;
+exports.ConversationSession = ConversationSession;
 exports.DEFAULT_BACKOFF = DEFAULT_BACKOFF;
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DEFAULT_CONTEXT_WARNING_THRESHOLD = DEFAULT_CONTEXT_WARNING_THRESHOLD;
+exports.DEFAULT_EMBED_BATCH_SIZE = DEFAULT_EMBED_BATCH_SIZE;
+exports.DEFAULT_EMBED_CONCURRENCY = DEFAULT_EMBED_CONCURRENCY;
 exports.DEFAULT_FAILOVER_CODES = DEFAULT_FAILOVER_CODES;
+exports.DEFAULT_FETCH_BACKOFF_CONFIG = DEFAULT_FETCH_BACKOFF_CONFIG;
 exports.DEFAULT_RETRY_CONFIG = DEFAULT_RETRY_CONFIG;
 exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
 exports.EndpointRegistry = EndpointRegistry;
 exports.GEN_AI_SYSTEM_OLLAMA = GEN_AI_SYSTEM_OLLAMA;
 exports.HttpClient = HttpClient;
+exports.IMAGE_TOKEN_ESTIMATE = IMAGE_TOKEN_ESTIMATE;
+exports.KEEP_ALIVE_INDEFINITE = KEEP_ALIVE_INDEFINITE;
+exports.KEEP_ALIVE_UNLOAD = KEEP_ALIVE_UNLOAD;
+exports.KNOWN_DONE_REASONS = KNOWN_DONE_REASONS;
+exports.MAX_SYSTEM_ONE_IMAGES_BYTES = MAX_SYSTEM_ONE_IMAGES_BYTES;
+exports.MAX_SYSTEM_ONE_REQUEST_BYTES = MAX_SYSTEM_ONE_REQUEST_BYTES;
 exports.McpBridge = McpBridge;
 exports.ModelsClient = ModelsClient;
 exports.NANOS_PER_MS = NANOS_PER_MS;
 exports.NANOS_PER_SECOND = NANOS_PER_SECOND;
 exports.NOOP_LOGGER = NOOP_LOGGER;
 exports.OLLAMA_CLOUD_BASE_URL = OLLAMA_CLOUD_BASE_URL;
+exports.OLLAMA_FALLBACK_CONTEXT_LENGTH = OLLAMA_FALLBACK_CONTEXT_LENGTH;
 exports.OllamaAbortError = OllamaAbortError;
 exports.OllamaAgentMaxIterationsError = OllamaAgentMaxIterationsError;
 exports.OllamaAgentMaxToolCallsError = OllamaAgentMaxToolCallsError;
 exports.OllamaAuthError = OllamaAuthError;
+exports.OllamaBadGatewayError = OllamaBadGatewayError;
 exports.OllamaClient = OllamaClient;
 exports.OllamaClientError = OllamaClientError;
 exports.OllamaGenericClientError = OllamaGenericClientError;
@@ -5543,6 +7108,7 @@ exports.OllamaMcpError = OllamaMcpError;
 exports.OllamaModelRoutingError = OllamaModelRoutingError;
 exports.OllamaNetworkError = OllamaNetworkError;
 exports.OllamaNotFoundError = OllamaNotFoundError;
+exports.OllamaOverloadedError = OllamaOverloadedError;
 exports.OllamaQuotaExceededError = OllamaQuotaExceededError;
 exports.OllamaRateLimitError = OllamaRateLimitError;
 exports.OllamaRequestTooLargeError = OllamaRequestTooLargeError;
@@ -5553,6 +7119,7 @@ exports.OllamaServerVersionUnknownError = OllamaServerVersionUnknownError;
 exports.OllamaSkillInvalidError = OllamaSkillInvalidError;
 exports.OllamaSkillNotFoundError = OllamaSkillNotFoundError;
 exports.OllamaStream = OllamaStream;
+exports.OllamaStreamError = OllamaStreamError;
 exports.OllamaTimeoutError = OllamaTimeoutError;
 exports.OllamaToolTimeoutError = OllamaToolTimeoutError;
 exports.OllamaToolValidationError = OllamaToolValidationError;
@@ -5563,27 +7130,49 @@ exports.OpenAICompletionStream = OpenAICompletionStream;
 exports.OpenAIResponsesStream = OpenAIResponsesStream;
 exports.OpenAIResponsesStreamError = OpenAIResponsesStreamError;
 exports.QuotaManager = QuotaManager;
+exports.RETRYABLE_STATUS_CODES = RETRYABLE_STATUS_CODES;
+exports.ResponsesModule = ResponsesModule;
+exports.ToolCallAccumulator = ToolCallAccumulator;
 exports.ToolRegistry = ToolRegistry;
 exports.addSpanEvent = addSpanEvent;
 exports.applySkill = applySkill;
+exports.batchEmbed = batchEmbed;
 exports.calculateBackoff = calculateBackoff;
+exports.checkChatContext = checkChatContext;
 exports.checkEndpointHealth = checkEndpointHealth;
+exports.checkGenerateContext = checkGenerateContext;
 exports.composeMiddleware = composeMiddleware;
+exports.contextWarningMessage = contextWarningMessage;
 exports.createConsoleLogger = createConsoleLogger;
 exports.createDecision = createDecision;
 exports.createOllamaCloudFreeTierQuota = createOllamaCloudFreeTierQuota;
 exports.createTimeoutSignal = createTimeoutSignal;
 exports.defineTool = defineTool;
 exports.detectModelCapabilities = detectModelCapabilities;
+exports.embedBatchOverflowMessage = embedBatchOverflowMessage;
 exports.encodeImage = encodeImage;
+exports.estimateChatRequestTokens = estimateChatRequestTokens;
+exports.estimateGenerateRequestTokens = estimateGenerateRequestTokens;
+exports.estimateSystemOneRequestBytes = estimateSystemOneRequestBytes;
+exports.estimateTokens = estimateTokens;
 exports.extractUsage = extractUsage;
+exports.fetchWithBackoff = fetchWithBackoff;
+exports.findOversizedEmbedInputs = findOversizedEmbedInputs;
+exports.imageStringNeedsResolution = imageStringNeedsResolution;
 exports.inferRuntimeMode = inferRuntimeMode;
+exports.isKeepAliveSugar = isKeepAliveSugar;
+exports.isKnownDoneReason = isKnownDoneReason;
+exports.isSameToolCall = isSameToolCall;
 exports.listAllMcpTools = listAllMcpTools;
 exports.listAvailableModels = listAvailableModels;
 exports.loadMcpTools = loadMcpTools;
 exports.mapError = mapError;
+exports.mergeToolCall = mergeToolCall;
+exports.mergeToolCallArgumentsString = mergeToolCallArgumentsString;
+exports.mergeToolCallArrays = mergeToolCallArrays;
 exports.normalizeChatStream = normalizeChatStream;
 exports.normalizeGenerateStream = normalizeGenerateStream;
+exports.normalizeKeepAlive = normalizeKeepAlive;
 exports.normalizeProgressStream = normalizeProgressStream;
 exports.parseFrontmatter = parseFrontmatter;
 exports.parseNdjsonStream = parseNdjsonStream;
@@ -5591,6 +7180,7 @@ exports.parseSseStream = parseSseStream;
 exports.parseStructuredOutput = parseStructuredOutput;
 exports.registerMcpTools = registerMcpTools;
 exports.resolveCredentialEndpoints = resolveCredentialEndpoints;
+exports.resolveImageInput = resolveImageInput;
 exports.setSpanError = setSpanError;
 exports.toDataStream = toDataStream;
 exports.toResponse = toResponse;