@nemesis-oss/ollama-sdk 1.19.0 → 1.20.0

package/dist/index.cjs

@@ -303,6 +303,17 @@ var OllamaToolTimeoutError = class extends OllamaClientError {
     this.timeoutMs = options.timeoutMs;
   }
 };
+var OllamaCloudModelVersionError = class extends OllamaClientError {
+  model;
+  serverVersion;
+  minRequiredVersion;
+  constructor(message, options) {
+    super(message, { ...options, code: "cloud_model_version", retryable: false });
+    this.model = options.model;
+    this.serverVersion = options.serverVersion;
+    this.minRequiredVersion = options.minRequiredVersion;
+  }
+};
 var OllamaUnsupportedCapabilityError = class extends OllamaClientError {
   capability;
   constructor(message, options) {
@@ -428,6 +439,43 @@ function isNetworkLevelError(error) {
   }
   return false;
 }
+function lookupHeader(headers, name) {
+  if (headers === void 0) {
+    return void 0;
+  }
+  const needle = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === needle) {
+      return value;
+    }
+  }
+  return void 0;
+}
+var HTTP_DATE_PATTERN = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+function parseRetryAfterMs(headerValue, now = Date.now()) {
+  if (headerValue === void 0) {
+    return void 0;
+  }
+  const trimmed = headerValue.trim();
+  if (trimmed === "") {
+    return void 0;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    if (!Number.isSafeInteger(seconds)) {
+      return void 0;
+    }
+    return seconds * 1e3;
+  }
+  if (!HTTP_DATE_PATTERN.test(trimmed)) {
+    return void 0;
+  }
+  const instant = Date.parse(trimmed);
+  if (Number.isNaN(instant)) {
+    return void 0;
+  }
+  return Math.max(0, instant - now);
+}
 function statusToError(status, message, options) {
   if (status === 401 || status === 403) {
     return new OllamaAuthError(message, { ...options, status });
@@ -439,7 +487,8 @@ function statusToError(status, message, options) {
     return new OllamaNotFoundError(message, { ...options, status });
   }
   if (status === 429) {
-    return new OllamaRateLimitError(message, { ...options, status });
+    const retryAfterMs = parseRetryAfterMs(lookupHeader(options.response?.headers, "retry-after"));
+    return new OllamaRateLimitError(message, { ...options, status, retryAfterMs });
   }
   if (status === 502) {
     return new OllamaBadGatewayError(message, { ...options });
@@ -1142,6 +1191,21 @@ function sameHeaders(actual, expected) {
   const expectedKeys = Object.keys(expectedEntries);
   return actualKeys.length === expectedKeys.length && expectedKeys.every((key) => actualEntries[key] === expectedEntries[key]);
 }
+function retryAfterHeaderFrom(response) {
+  try {
+    const headers = response?.headers;
+    if (headers === null || headers === void 0 || typeof headers.get !== "function") {
+      return void 0;
+    }
+    const value = headers.get("retry-after");
+    if (value === null || value === "") {
+      return void 0;
+    }
+    return { "retry-after": value };
+  } catch {
+    return void 0;
+  }
+}
 var HttpClient = class {
   baseUrl;
   apiKey;
@@ -1209,7 +1273,12 @@ var HttpClient = class {
             durationMs: Date.now() - startedAt,
             error: mapError(new Error(`HTTP ${response2.status}`), {
               request: { method: request.method, url: request.url },
-              response: { status: response2.status }
+              // Mirrors the middleware path, which reports context.headers:
+              // a 429 lifecycle event carries the server's Retry-After.
+              response: {
+                status: response2.status,
+                headers: retryAfterHeaderFrom(response2)
+              }
             }),
             timestamp: Date.now()
           });
@@ -1315,7 +1384,11 @@ var HttpClient = class {
             const message = typeof errorBody === "object" && errorBody !== null && "error" in errorBody ? String(errorBody.error) : `HTTP ${response.status} ${response.statusText}`;
             throw mapError(new Error(message), {
               request: { method, url },
-              response: { status: response.status, body: errorBody }
+              response: {
+                status: response.status,
+                headers: retryAfterHeaderFrom(response),
+                body: errorBody
+              }
             });
           }
           if (options.method === "HEAD" || response.status === 204) {
@@ -1380,7 +1453,11 @@ var HttpClient = class {
             const errorText = await response.text();
             throw mapError(new Error(errorText || `HTTP ${response.status}`), {
               request: { method, url },
-              response: { status: response.status, body: errorText }
+              response: {
+                status: response.status,
+                headers: retryAfterHeaderFrom(response),
+                body: errorText
+              }
             });
           }
           if (!response.body) {
@@ -1444,7 +1521,11 @@ var HttpClient = class {
             const errorText = await response.text();
             throw mapError(new Error(errorText || `HTTP ${response.status}`), {
               request: { method, url },
-              response: { status: response.status, body: errorText }
+              response: {
+                status: response.status,
+                headers: retryAfterHeaderFrom(response),
+                body: errorText
+              }
             });
           }
           if (!response.body) {
@@ -1750,7 +1831,7 @@ function contextWarningMessage(check2, kind) {
   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.${suggestion} 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.${suggestion} Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
+  return `${where}: estimated prompt size ${estimate} outright exceeds the worst-case floor for the unset-\`num_ctx\` window (${OLLAMA_FALLBACK_CONTEXT_LENGTH} tokens \u2014 current daemons default higher, tiered by VRAM: 4096 / 32768 / 262144; \`OLLAMA_CONTEXT_LENGTH\` can override either way). If your daemon's effective window is that small, 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 \u2014 or discover the real one via \`client.models.getContextLength()\` \u2014 to make truncation visible and controllable.${suggestion} Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
 }
 
 // src/context-discovery.ts
@@ -2478,6 +2559,12 @@ function sleep(ms, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
+function retryDelayMs(error, attempt, backoff) {
+  if (error instanceof OllamaRateLimitError && error.retryAfterMs !== void 0) {
+    return error.retryAfterMs;
+  }
+  return calculateBackoff(attempt, backoff);
+}
 async function withRetry(operation, config = DEFAULT_RETRY_CONFIG, signal) {
   let attempt = 0;
   while (true) {
@@ -2489,7 +2576,7 @@ async function withRetry(operation, config = DEFAULT_RETRY_CONFIG, signal) {
       if (attempt >= config.maxRetries || !shouldRetry(error, attempt)) {
         throw error;
       }
-      const delayMs = calculateBackoff(attempt, config.backoff);
+      const delayMs = retryDelayMs(error, attempt, config.backoff);
       config.onRetry?.(error, attempt, delayMs);
       await sleep(delayMs, signal);
       attempt += 1;
@@ -2658,7 +2745,8 @@ var ModelsClient = class {
   }
   /**
    * Discovers the model's real context window from the server — no more
-   * 2048/4096 guesswork. Consults, in precedence order:
+   * default-window guesswork (current daemons tier the unset-`num_ctx`
+   * default by VRAM: 4k / 32k / 256k). Consults, in precedence order:
    *
    *   1. `GET /api/ps` — the window the **running instance actually
    *      allocated** (exact, reflects the Modelfile `num_ctx` default and
@@ -2670,7 +2758,7 @@ var ModelsClient = class {
    *   3. `POST /api/show` `model_info["<arch>.context_length"]` — the
    *      model's **native GGUF maximum** (a ceiling to raise `num_ctx`
    *      toward, not the allocated window).
-   *   4. Fallback — Ollama's conservative unset-`num_ctx` default (2048).
+   *   4. Fallback — the 2048 worst-case floor for the unset-`num_ctx` window.
    *
    * The result carries every signal it found, so `nativeContextLength:
    * 131072` vs `contextLength: 4096` (a 32× gap seen in the official API
@@ -4156,6 +4244,9 @@ var ShowResponseSchema = zod.z.object({
   modified_at: zod.z.string().optional(),
   details: zod.z.object({}).optional(),
   template: zod.z.string().optional(),
+  renderer: zod.z.string().optional(),
+  parser: zod.z.string().optional(),
+  template_source: zod.z.string().optional(),
   capabilities: zod.z.array(zod.z.string()).optional(),
   model_info: zod.z.object({}).optional()
 });
@@ -4247,9 +4338,26 @@ var UsageMetricsSchema = zod.z.object({
   output_tokens: zod.z.number().optional()
 });
 
+// src/generated/models/UsageGroup.schema.ts
+var UsageGroupSchema = zod.z.intersection(
+  UsageMetricsSchema,
+  zod.z.object({
+    model: zod.z.string()
+  })
+);
+
+// src/generated/models/UsageSummary.schema.ts
+var UsageSummarySchema = zod.z.intersection(
+  UsageMetricsSchema,
+  zod.z.object({
+    groups: zod.z.array(UsageGroupSchema).optional(),
+    remainder: UsageMetricsSchema.optional()
+  })
+);
+
 // src/generated/models/UsageBucket.schema.ts
 var UsageBucketSchema = zod.z.intersection(
-  UsageMetricsSchema,
+  UsageSummarySchema,
   zod.z.object({
     from: zod.z.string(),
     until: zod.z.string(),
@@ -4262,9 +4370,10 @@ var UsageResponseSchema = zod.z.object({
   range: zod.z.enum(["24h", "7d", "30d"]),
   scope: zod.z.enum(["self", "team"]),
   granularity: zod.z.enum(["hour", "day"]),
+  group_by: zod.z.enum(["model"]).optional(),
   from: zod.z.string(),
   until: zod.z.string(),
-  totals: UsageMetricsSchema,
+  totals: UsageSummarySchema,
   buckets: zod.z.array(UsageBucketSchema)
 });
 var VersionResponseSchema = zod.z.object({
@@ -5707,6 +5816,29 @@ function createDecision(client) {
   };
 }
 
+// src/system-one.ts
+var MAX_SYSTEM_ONE_IMAGES_BYTES = 32 * 1024 * 1024;
+var MAX_SYSTEM_ONE_REQUEST_BYTES = 64 * 1024;
+var CLOUD_MODEL_SUFFIX = ":cloud";
+var CLOUD_MODEL_MIN_OLLAMA_VERSION = "0.40.5";
+function isCloudModel(model) {
+  return model.endsWith(CLOUD_MODEL_SUFFIX);
+}
+function compareOllamaVersions(a, b) {
+  const pa = a.split(".").map((s) => Number.parseInt(s, 10) || 0);
+  const pb = b.split(".").map((s) => Number.parseInt(s, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va !== vb) return va - vb;
+  }
+  return 0;
+}
+function estimateSystemOneRequestBytes(request, options) {
+  const body = options?.excludeImages && request.images !== void 0 ? { ...request, images: void 0 } : request;
+  return new TextEncoder().encode(JSON.stringify(body)).byteLength;
+}
+
 // src/client.ts
 var logicalRequestSequence = 0;
 function createLogicalRequestId() {
@@ -6333,9 +6465,13 @@ var OllamaClient = class _OllamaClient {
    * launch): `model` also accepts cloud models such as `clef:cloud` —
    * cloud models require Ollama >= 0.40.5 or the hosted
    * `https://ollama.com` endpoint. Requires Ollama >= 0.35.0 locally.
-   * The runtime enforces the version constraint automatically (lazily
+   * Both version constraints are enforced client-side before the request
+   * is sent: the blanket 0.35.0 floor by the generated runtime (lazily
    * fetching `/api/version` when `enforceVersion` is `'auto'` or
-   * `'strict'`). Request size is checked client-side as a dual cap:
+   * `'strict'`), and the model-dependent 0.40.5 cloud gate by this
+   * wrapper — a cloud model through a local server older than 0.40.5
+   * throws {@link OllamaCloudModelVersionError} without a round-trip
+   * (ADR 0036). Request size is checked client-side as a dual cap:
    * text and schema (images excluded) within 64 KiB AND the whole
    * request within 32 MiB.
    *
@@ -6360,10 +6496,44 @@ var OllamaClient = class _OllamaClient {
    * `client.native.systemOne(request)` directly.
    */
   async systemOne(request) {
+    await this.assertCloudModelSupported(request.model);
     return this.native.systemOne(
       request
     );
   }
+  /**
+   * Cloud-model version gate for {@link systemOne} — throws
+   * {@link OllamaCloudModelVersionError} when a cloud model is requested
+   * through a local server older than {@link CLOUD_MODEL_MIN_OLLAMA_VERSION}
+   * (0.40.5). No-op for non-cloud models and for cloud-mode clients
+   * (hosted `ollama.com`). The `/api/version` probe goes through the normal
+   * failover machinery and is cached per client instance (reset on failure,
+   * so a later gated call retries), so at most one extra round-trip happens
+   * across all gated calls.
+   */
+  async assertCloudModelSupported(model) {
+    if (!isCloudModel(model)) return;
+    const candidates = this.registry.candidates();
+    const baseUrl = candidates[0]?.baseUrl ?? DEFAULT_BASE_URL;
+    if (inferRuntimeMode(baseUrl) !== "local") return;
+    let version;
+    try {
+      if (this.serverVersionCache === void 0) {
+        this.serverVersionCache = this.native.version().then((v) => v.version);
+      }
+      version = await this.serverVersionCache;
+    } catch {
+      this.serverVersionCache = void 0;
+      return;
+    }
+    if (version && compareOllamaVersions(version, CLOUD_MODEL_MIN_OLLAMA_VERSION) < 0) {
+      throw new OllamaCloudModelVersionError(
+        `System One cloud model "${model}" requires Ollama >= ${CLOUD_MODEL_MIN_OLLAMA_VERSION} when routed through a local server (this server reports ${version}). Upgrade Ollama, or point an endpoint at https://ollama.com.`,
+        { model, serverVersion: version, minRequiredVersion: CLOUD_MODEL_MIN_OLLAMA_VERSION }
+      );
+    }
+  }
+  serverVersionCache;
   // --- Web Endpoints ---
   /**
    * Ollama's hosted web search tool (`POST https://ollama.com/api/web_search`) — a fixed
@@ -6371,7 +6541,9 @@ var OllamaClient = class _OllamaClient {
    * 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.
+   * ever the one cloud endpoint to call. If the service answers 429 with a `Retry-After`
+   * header, the transport parses it into `OllamaRateLimitError.retryAfterMs` and the
+   * retry loop sleeps exactly that long instead of jittered backoff (see ADR 0035).
    */
   async webSearch(req) {
     const { count, max_results, ...rest } = req;
@@ -6402,14 +6574,24 @@ var OllamaClient = class _OllamaClient {
    * 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).
+   * behavior, which applies identically here. The pinned contract documents this
+   * endpoint's 429 with a `Retry-After` header ("Seconds to wait before retrying"),
+   * which the SDK parses into `OllamaRateLimitError.retryAfterMs` and honors verbatim
+   * when retrying. Query parameters mirror the official endpoint: `range`
+   * (`'24h' | '7d' | '30d'`, server default `'7d'`), `scope`
+   * (`'self' | 'team'`, server default `'self'`; team scope requires a team
+   * admin), and — since the 2026-10-22 pin (upstream 2476d5e) — `groupBy`
+   * (`group_by=model`), which makes `totals` and every bucket carry up to 10
+   * per-model `UsageGroup` entries plus a `remainder` roll-up, with the
+   * selection echoed back as `group_by` on the response.
    * Omitted options are left unset so the server applies its own defaults.
    *
    * ```ts
-   * const usage = await client.usage({ range: '24h' });
+   * const usage = await client.usage({ range: '24h', groupBy: 'model' });
    * console.log(usage.totals.request_count, usage.totals.usage_usd);
+   * for (const group of usage.totals.groups ?? []) {
+   *   console.log(group.model, group.usage_usd);
+   * }
    * for (const bucket of usage.buckets) {
    *   if (bucket.partial) continue; // current hour, still in progress
    *   // ...
@@ -6420,6 +6602,7 @@ var OllamaClient = class _OllamaClient {
     const params = new URLSearchParams();
     if (req.range !== void 0) params.set("range", req.range);
     if (req.scope !== void 0) params.set("scope", req.scope);
+    if (req.groupBy !== void 0) params.set("group_by", req.groupBy);
     const query = params.toString();
     return this.executeCloudRequest(
       (http, signal) => http.request({
@@ -6436,7 +6619,9 @@ var OllamaClient = class _OllamaClient {
    * 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.
+   * behavior, which applies identically here. Like `/api/usage`, the pinned contract
+   * documents this endpoint's 429 with a `Retry-After` header, parsed into
+   * `OllamaRateLimitError.retryAfterMs` and honored verbatim when retrying (ADR 0035).
    *
    * ```ts
    * const balance = await client.balance();
@@ -6722,6 +6907,21 @@ function sleep2(ms, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
+function retryAfterMsFromResponse(response) {
+  try {
+    const headers = response?.headers;
+    if (headers === null || headers === void 0 || typeof headers.get !== "function") {
+      return void 0;
+    }
+    const value = headers.get("retry-after");
+    if (value === null || value === "") {
+      return void 0;
+    }
+    return parseRetryAfterMs(value);
+  } catch {
+    return void 0;
+  }
+}
 async function fetchWithBackoff(input, init, config = {}) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   if (typeof fetchImpl !== "function") {
@@ -6743,7 +6943,8 @@ async function fetchWithBackoff(input, init, config = {}) {
         ...signal !== void 0 ? { signal } : {}
       });
       if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < maxRetries) {
-        const delayMs = calculateBackoff(attempt, backoff);
+        const serverDelayMs = response.status === 429 ? retryAfterMsFromResponse(response) : void 0;
+        const delayMs = serverDelayMs ?? calculateBackoff(attempt, backoff);
         config.onRetry?.(attempt, response.status, delayMs);
         await sleep2(delayMs, signal);
         continue;
@@ -8285,14 +8486,6 @@ function createModelAffinityScheduler(client, options) {
   return new ModelAffinityScheduler(client, options);
 }
 
-// src/system-one.ts
-var MAX_SYSTEM_ONE_IMAGES_BYTES = 32 * 1024 * 1024;
-var MAX_SYSTEM_ONE_REQUEST_BYTES = 64 * 1024;
-function estimateSystemOneRequestBytes(request, options) {
-  const body = options?.excludeImages && request.images !== void 0 ? { ...request, images: void 0 } : request;
-  return new TextEncoder().encode(JSON.stringify(body)).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;
@@ -8313,6 +8506,8 @@ exports.ATTR_URL_FULL = ATTR_URL_FULL;
 exports.Agent = Agent;
 exports.AnthropicCompatClient = AnthropicCompatClient;
 exports.AnthropicMessagesStream = AnthropicMessagesStream;
+exports.CLOUD_MODEL_MIN_OLLAMA_VERSION = CLOUD_MODEL_MIN_OLLAMA_VERSION;
+exports.CLOUD_MODEL_SUFFIX = CLOUD_MODEL_SUFFIX;
 exports.ConversationSession = ConversationSession;
 exports.DEFAULT_BACKOFF = DEFAULT_BACKOFF;
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
@@ -8351,6 +8546,7 @@ exports.OllamaAuthError = OllamaAuthError;
 exports.OllamaBadGatewayError = OllamaBadGatewayError;
 exports.OllamaClient = OllamaClient;
 exports.OllamaClientError = OllamaClientError;
+exports.OllamaCloudModelVersionError = OllamaCloudModelVersionError;
 exports.OllamaGenericClientError = OllamaGenericClientError;
 exports.OllamaIncompatibleModelError = OllamaIncompatibleModelError;
 exports.OllamaMcpError = OllamaMcpError;
@@ -8396,6 +8592,7 @@ exports.checkEndpointHealth = checkEndpointHealth;
 exports.checkGenerateContext = checkGenerateContext;
 exports.compactConversationHistory = compactConversationHistory;
 exports.compareDraftPerformance = compareDraftPerformance;
+exports.compareOllamaVersions = compareOllamaVersions;
 exports.composeMiddleware = composeMiddleware;
 exports.computeProgressPercent = computeProgressPercent;
 exports.contextWarningMessage = contextWarningMessage;
@@ -8428,6 +8625,7 @@ exports.formatWebFetchResult = formatWebFetchResult;
 exports.formatWebSearchResult = formatWebSearchResult;
 exports.imageStringNeedsResolution = imageStringNeedsResolution;
 exports.inferRuntimeMode = inferRuntimeMode;
+exports.isCloudModel = isCloudModel;
 exports.isKeepAliveSugar = isKeepAliveSugar;
 exports.isKnownDoneReason = isKnownDoneReason;
 exports.isModelResident = isModelResident;
@@ -8448,6 +8646,7 @@ exports.observeStream = observeStream;
 exports.onProgress = onProgress;
 exports.parseFrontmatter = parseFrontmatter;
 exports.parseNdjsonStream = parseNdjsonStream;
+exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.parseSseStream = parseSseStream;
 exports.parseStructuredOutput = parseStructuredOutput;
 exports.recommendContextWindow = recommendContextWindow;