@nemesis-oss/ollama-sdk 1.19.0 → 1.19.1

package/dist/index.cjs

@@ -428,6 +428,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 +476,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 +1180,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 +1262,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 +1373,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 +1442,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 +1510,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 +1820,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 +2548,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 +2565,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 +2734,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 +2747,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
@@ -6371,7 +6448,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,8 +6481,11 @@ 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`
+   * 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'`) 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.
    *
@@ -6436,7 +6518,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 +6806,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 +6842,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;
@@ -8448,6 +8548,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;