@nemesis-oss/ollama-sdk 1.19.0 → 1.19.1

package/dist/index.d.cts

@@ -1,10 +1,10 @@
 import { T as ThinkingMetadata, M as ModelResponse, R as RequestCancellationOptions, S as ShowRequestOptions, a as ShowResponse, P as PullRequestOptions, b as ProgressResponse, c as PushRequestOptions, C as CreateRequestOptions, D as DeleteRequestOptions, d as StatusResponse, e as CopyRequestOptions, f as PsResponse, V as VersionResponse, g as ToolParameters, h as ThinkValue, i as ToolCall, j as ChatRequestOptions, k as ModelOptions, l as ToolDefinition, F as FormatOption, m as ChatResponse, n as Message, G as GenerateRequestOptions, o as GenerateResponse, E as EmbedRequestOptions, p as EmbedResponse, q as EmbeddingsRequestOptions, r as EmbeddingsResponse, W as WebSearchRequestOptions, s as WebSearchResponse, t as WebFetchRequestOptions, u as WebFetchResponse, U as UsageRequestOptions, B as BalanceRequestOptions, v as PingResult, w as VisionInput } from './types-Y3u0FtdN.cjs';
 export { L as ListResponse, x as Logprob, y as LogprobToken, z as ModelDetails, A as Role, H as ToolCallFunction, I as ToolFunctionDefinition, J as ToolProperty, K as UsageRange, N as UsageScope, O as WebSearchResult, Q as imageStringNeedsResolution, X as resolveImageInput } from './types-Y3u0FtdN.cjs';
-import { H as HttpClient, F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-C28YEAHC.cjs';
-export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NETWORK_ERROR_CODES, r as NOOP_LOGGER, s as NextFunction, t as OllamaAbortError, u as OllamaAgentMaxIterationsError, v as OllamaAgentMaxToolCallsError, w as OllamaAgentToolLoopError, x as OllamaAuthError, y as OllamaBadGatewayError, z as OllamaClientError, J as OllamaClientErrorOptions, K as OllamaErrorRequestContext, Q as OllamaErrorResponseContext, U as OllamaGenericClientError, V as OllamaIncompatibleModelError, W as OllamaMcpError, X as OllamaModelRoutingError, Y as OllamaNetworkError, Z as OllamaNotFoundError, _ as OllamaOverloadedError, $ as OllamaPaymentRequiredError, a0 as OllamaQuotaExceededError, a1 as OllamaRateLimitError, a2 as OllamaRequestTooLargeError, a3 as OllamaRequestValidationError, a4 as OllamaResponseValidationError, a5 as OllamaServerError, a6 as OllamaServerVersionUnknownError, a7 as OllamaSkillInvalidError, a8 as OllamaSkillNotFoundError, a9 as OllamaStreamError, aa as OllamaTimeoutError, ab as OllamaToolTimeoutError, ac as OllamaToolValidationError, ad as OllamaUnsupportedCapabilityError, ae as RequestContext, af as RequestLifecycleEvent, ag as ResponseContext, ah as SseEvent, ai as ThinkingEvent, aj as TokenEvent, ak as ToolCallEvent, al as composeMiddleware, am as createConsoleLogger, an as extractUsage, ao as isNetworkLevelError, ap as mapError, aq as parseSseStream } from './runtime-C28YEAHC.cjs';
+import { H as HttpClient, F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-CjCriL5A.cjs';
+export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NETWORK_ERROR_CODES, r as NOOP_LOGGER, s as NextFunction, t as OllamaAbortError, u as OllamaAgentMaxIterationsError, v as OllamaAgentMaxToolCallsError, w as OllamaAgentToolLoopError, x as OllamaAuthError, y as OllamaBadGatewayError, z as OllamaClientError, J as OllamaClientErrorOptions, K as OllamaErrorRequestContext, Q as OllamaErrorResponseContext, U as OllamaGenericClientError, V as OllamaIncompatibleModelError, W as OllamaMcpError, X as OllamaModelRoutingError, Y as OllamaNetworkError, Z as OllamaNotFoundError, _ as OllamaOverloadedError, $ as OllamaPaymentRequiredError, a0 as OllamaQuotaExceededError, a1 as OllamaRateLimitError, a2 as OllamaRequestTooLargeError, a3 as OllamaRequestValidationError, a4 as OllamaResponseValidationError, a5 as OllamaServerError, a6 as OllamaServerVersionUnknownError, a7 as OllamaSkillInvalidError, a8 as OllamaSkillNotFoundError, a9 as OllamaStreamError, aa as OllamaTimeoutError, ab as OllamaToolTimeoutError, ac as OllamaToolValidationError, ad as OllamaUnsupportedCapabilityError, ae as RequestContext, af as RequestLifecycleEvent, ag as ResponseContext, ah as SseEvent, ai as ThinkingEvent, aj as TokenEvent, ak as ToolCallEvent, al as composeMiddleware, am as createConsoleLogger, an as extractUsage, ao as isNetworkLevelError, ap as mapError, aq as parseRetryAfterMs, ar as parseSseStream } from './runtime-CjCriL5A.cjs';
 import { z } from 'zod';
-import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-DIPnBwlf.cjs';
-export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as OllamaOpenAIChatContentPart, a4 as OllamaOpenAIChatMessage, a5 as OllamaOpenAICompletionRequest, a6 as OllamaOpenAIEmbeddingRequest, a7 as OllamaOpenAIImageDataUrl, a8 as OllamaOpenAIReasoningEffort, a9 as OllamaOpenAIResponsesRequest, aa as OpenAIChatCompletionChoice, b as OpenAIChatCompletionChunk, ab as OpenAIChatCompletionChunkChoice, ac as OpenAIChatCompletionDelta, O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, ad as OpenAIChatCompletionStream, ae as OpenAICompletionChoice, e as OpenAICompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, af as OpenAICompletionStream, ag as OpenAIContentPart, ah as OpenAIEmbeddingInput, ai as OpenAIEmbeddingItem, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, aj as OpenAIFunctionDefinition, ak as OpenAIImageUrlContentPart, h as OpenAIListModelsResponse, al as OpenAIMessage, i as OpenAIModelItem, am as OpenAIReasoningEffort, an as OpenAIResponseFormat, ao as OpenAIResponsesCompletedEvent, ap as OpenAIResponsesContentPartAddedEvent, aq as OpenAIResponsesContentPartDoneEvent, ar as OpenAIResponsesCreatedEvent, as as OpenAIResponsesError, at as OpenAIResponsesEventBase, au as OpenAIResponsesFailedEvent, av as OpenAIResponsesFunctionCallArgumentsDeltaEvent, aw as OpenAIResponsesFunctionCallArgumentsDoneEvent, ax as OpenAIResponsesInProgressEvent, ay as OpenAIResponsesIncompleteDetails, az as OpenAIResponsesIncompleteEvent, aA as OpenAIResponsesOutputContent, aB as OpenAIResponsesOutputFunctionCall, aC as OpenAIResponsesOutputItem, aD as OpenAIResponsesOutputItemAddedEvent, aE as OpenAIResponsesOutputItemDoneEvent, aF as OpenAIResponsesOutputMessage, aG as OpenAIResponsesOutputReasoning, aH as OpenAIResponsesOutputRefusal, aI as OpenAIResponsesOutputTextContent, aJ as OpenAIResponsesOutputTextDeltaEvent, aK as OpenAIResponsesOutputTextDoneEvent, aL as OpenAIResponsesQueuedEvent, aM as OpenAIResponsesReasoningSummaryPartAddedEvent, aN as OpenAIResponsesReasoningSummaryPartDoneEvent, aO as OpenAIResponsesReasoningSummaryTextDeltaEvent, aP as OpenAIResponsesReasoningSummaryTextDoneEvent, aQ as OpenAIResponsesReasoningTextDeltaEvent, aR as OpenAIResponsesReasoningTextDoneEvent, aS as OpenAIResponsesRefusalDeltaEvent, aT as OpenAIResponsesRefusalDoneEvent, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, aU as OpenAIResponsesStatus, aV as OpenAIResponsesStream, aW as OpenAIResponsesStreamError, l as OpenAIResponsesStreamEvent, aX as OpenAIResponsesUsage, aY as OpenAIStreamOptions, aZ as OpenAITextContentPart, a_ as OpenAITool, a$ as OpenAIToolCall, b0 as OpenAIToolCallDelta, b1 as OpenAIUsage, b2 as SystemOneConfidence, b3 as SystemOneProbabilities } from './anthropic-DIPnBwlf.cjs';
+import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-Bf16hGLL.cjs';
+export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as OllamaOpenAIChatContentPart, a4 as OllamaOpenAIChatMessage, a5 as OllamaOpenAICompletionRequest, a6 as OllamaOpenAIEmbeddingRequest, a7 as OllamaOpenAIImageDataUrl, a8 as OllamaOpenAIReasoningEffort, a9 as OllamaOpenAIResponsesRequest, aa as OpenAIChatCompletionChoice, b as OpenAIChatCompletionChunk, ab as OpenAIChatCompletionChunkChoice, ac as OpenAIChatCompletionDelta, O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, ad as OpenAIChatCompletionStream, ae as OpenAICompletionChoice, e as OpenAICompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, af as OpenAICompletionStream, ag as OpenAIContentPart, ah as OpenAIEmbeddingInput, ai as OpenAIEmbeddingItem, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, aj as OpenAIFunctionDefinition, ak as OpenAIImageUrlContentPart, h as OpenAIListModelsResponse, al as OpenAIMessage, i as OpenAIModelItem, am as OpenAIReasoningEffort, an as OpenAIResponseFormat, ao as OpenAIResponsesCompletedEvent, ap as OpenAIResponsesContentPartAddedEvent, aq as OpenAIResponsesContentPartDoneEvent, ar as OpenAIResponsesCreatedEvent, as as OpenAIResponsesError, at as OpenAIResponsesEventBase, au as OpenAIResponsesFailedEvent, av as OpenAIResponsesFunctionCallArgumentsDeltaEvent, aw as OpenAIResponsesFunctionCallArgumentsDoneEvent, ax as OpenAIResponsesInProgressEvent, ay as OpenAIResponsesIncompleteDetails, az as OpenAIResponsesIncompleteEvent, aA as OpenAIResponsesOutputContent, aB as OpenAIResponsesOutputFunctionCall, aC as OpenAIResponsesOutputItem, aD as OpenAIResponsesOutputItemAddedEvent, aE as OpenAIResponsesOutputItemDoneEvent, aF as OpenAIResponsesOutputMessage, aG as OpenAIResponsesOutputReasoning, aH as OpenAIResponsesOutputRefusal, aI as OpenAIResponsesOutputTextContent, aJ as OpenAIResponsesOutputTextDeltaEvent, aK as OpenAIResponsesOutputTextDoneEvent, aL as OpenAIResponsesQueuedEvent, aM as OpenAIResponsesReasoningSummaryPartAddedEvent, aN as OpenAIResponsesReasoningSummaryPartDoneEvent, aO as OpenAIResponsesReasoningSummaryTextDeltaEvent, aP as OpenAIResponsesReasoningSummaryTextDoneEvent, aQ as OpenAIResponsesReasoningTextDeltaEvent, aR as OpenAIResponsesReasoningTextDoneEvent, aS as OpenAIResponsesRefusalDeltaEvent, aT as OpenAIResponsesRefusalDoneEvent, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, aU as OpenAIResponsesStatus, aV as OpenAIResponsesStream, aW as OpenAIResponsesStreamError, l as OpenAIResponsesStreamEvent, aX as OpenAIResponsesUsage, aY as OpenAIStreamOptions, aZ as OpenAITextContentPart, a_ as OpenAITool, a$ as OpenAIToolCall, b0 as OpenAIToolCallDelta, b1 as OpenAIUsage, b2 as SystemOneConfidence, b3 as SystemOneProbabilities } from './anthropic-Bf16hGLL.cjs';
 import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-C4QxEZOS.cjs';
 export { d as AppliedSkillResult, e as ApplySkillOptions, P as ParsedFrontmatter, S as Skill, f as SkillFrontmatter, g as SkillSummary, h as ToolExecutionContext, i as ToolExecutionFailure, j as ToolExecutionSuccess, k as ToolRegistryOptions, l as applySkill, p as parseFrontmatter } from './compose-C4QxEZOS.cjs';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.cjs';
@@ -219,7 +219,10 @@ declare function listAvailableModels(http: HttpClient): Promise<ModelResponse[]>
  * Dynamic context-window discovery.
  *
  * Guessing context windows ("it's probably 2048… or 4096?") is how silent
- * truncation happens. Ollama advertises the real numbers in two places, and
+ * truncation happens — and current daemons make the guess worse, not better:
+ * the unset-`num_ctx` default is tiered by VRAM (4k / 32k / 256k), so a
+ * hardcoded assumption is now wrong in both directions. Ollama advertises
+ * the real numbers in two places, and
  * they answer *different questions*:
  *
  *   - **`GET /api/ps`** reports `context_length` for every currently-running
@@ -262,14 +265,14 @@ type ContextLengthSource =
  | 'parameters'
 /** `POST /api/show` `model_info["*.context_length"]` — native GGUF maximum. */
  | 'model-info'
-/** Nothing discoverable — Ollama's conservative unset-`num_ctx` default (2048). */
+/** Nothing discoverable — the 2048 worst-case floor for the unset-`num_ctx` window (current daemons tier by VRAM: 4k / 32k / 256k). */
  | 'fallback';
 /** Result of {@link ModelsClient.getContextLength}. */
 interface DiscoveredContextLength {
     /**
      * The effective context window to program against, resolved by precedence:
      * `running` (exact, when loaded) → `parameters` (Modelfile default) →
-     * `model-info` (native max) → `2048` fallback.
+     * `model-info` (native max) → worst-case `2048` fallback.
      */
     readonly contextLength: number;
     /** Which source produced {@link contextLength}. */
@@ -329,7 +332,9 @@ interface ContextLengthSignals {
  *      (Ollama's conservative default), so native is a *ceiling*, not an
  *      expectation.
  *   4. **Fallback** — {@link OLLAMA_FALLBACK_CONTEXT_LENGTH} (2048), the
- *      conservative server-side default, so the result is always actionable.
+ *      worst-case floor for the unset-`num_ctx` window (current daemons tier
+ *      by VRAM up to 262,144), so the result is always actionable and can
+ *      never over-estimate a real window.
  *
  * Pure — used by `ModelsClient.getContextLength()` and exported for callers
  * that already hold `/api/ps` / `/api/show` responses.
@@ -363,6 +368,13 @@ interface RetryConfig {
 declare const DEFAULT_RETRY_CONFIG: RetryConfig;
 /**
  * Executes an async operation with retries according to config.
+ *
+ * Retry pacing: a 429 whose `Retry-After` header produced
+ * `OllamaRateLimitError.retryAfterMs` sleeps exactly that long before the
+ * next attempt (server authority — see {@link retryDelayMs}); all other
+ * retryable errors sleep a full-jitter exponential backoff. The delay
+ * actually used is reported to `onRetry` either way, and remains abortable
+ * through `signal` for the whole wait.
  */
 declare function withRetry<T>(operation: (attempt: number) => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
 
@@ -758,9 +770,11 @@ interface OllamaClientConfig {
      * Default context window (`num_ctx`) applied to every `chat`/`generate`
      * request that doesn't set `options.num_ctx` itself. Injected as
      * `options.num_ctx` on the wire, making the effective window explicit
-     * instead of leaving it to Ollama's server default (commonly 2048–4096,
-     * model-dependent) — which **silently truncates** prompts that don't fit,
-     * with no error and no warning. See `src/context-safety.ts`.
+     * instead of leaving it to Ollama's VRAM-tiered server default (4,096
+     * tokens below 24 GiB, 32,768 at 24–48 GiB, 262,144 at 48 GiB and up;
+     * daemon-wide override via `OLLAMA_CONTEXT_LENGTH`) — which **silently
+     * truncates** prompts that don't fit, with no error and no warning. See
+     * `src/context-safety.ts`.
      */
     readonly defaultContextLength?: number;
     /**
@@ -887,7 +901,8 @@ declare class ModelsClient {
     ps(request?: RequestCancellationOptions): Promise<PsResponse>;
     /**
      * 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
@@ -899,7 +914,7 @@ declare class ModelsClient {
      *   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
@@ -1378,8 +1393,8 @@ declare function sanitizeHistoryForNextTurn(messages: readonly Message[], option
 interface SessionCompactionOptions {
     /**
      * Token budget for the compacted history. Defaults to the session's own
-     * window: `options.num_ctx` from the session config, or Ollama's
-     * conservative 2048 fallback when unset — pair with
+     * window: `options.num_ctx` from the session config, or the 2048
+     * worst-case fallback when unset — pair with
      * `client.models.getContextLength()` to program against the real window.
      */
     readonly maxEstimatedTokens?: number | undefined;
@@ -2436,7 +2451,9 @@ declare 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).
      */
     webSearch(req: WebSearchRequestOptions): Promise<WebSearchResponse>;
     /**
@@ -2451,8 +2468,11 @@ declare 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.
      *
@@ -2472,7 +2492,9 @@ declare 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();
@@ -2584,8 +2606,11 @@ declare function createTimeoutSignal(timeoutMs?: number, userSignal?: AbortSigna
  * fan-out embed batches, speculative-decoding pipelines) can't always
  * predict saturation ahead of time, so the SDK exposes this helper —
  * a thin wrapper around `fetch` that retries 503/429 responses with
- * the same jittered exponential backoff used by the SDK's internal
- * transport (see `./backoff.ts` and `./retry.ts`).
+ * the same retry discipline used by the SDK's internal transport (see
+ * `./backoff.ts` and `./retry.ts`): jittered exponential backoff, except
+ * that a 429 carrying `Retry-After` (RFC 9110 § 10.2.3) is honored
+ * verbatim — the server said when to retry, and sleeping less than that
+ * would only compound the rate limiting.
  *
  * The helper is intentionally standalone: it works with any
  * `fetch`-shaped function (browser `globalThis.fetch`, `undici`, an
@@ -2624,8 +2649,10 @@ interface FetchWithBackoffConfig {
      *
      * Receives the attempt index (0-based for the original request,
      * 1+ for retries), the HTTP status that triggered the retry
-     * (or `0` for network-level failures), and the calculated delay
-     * in milliseconds (already jittered).
+     * (or `0` for network-level failures), and the delay
+     * in milliseconds that will be slept (the server's `Retry-After`
+     * verbatim on a 429 that carried one; otherwise the jittered
+     * backoff sample).
      */
     readonly onRetry?: ((attempt: number, status: number, delayMs: number) => void) | undefined;
     /**
@@ -2667,11 +2694,14 @@ declare const DEFAULT_FETCH_BACKOFF_CONFIG: {
  * Wrapper around any `fetch`-shaped function that retries HTTP 429 / 503
  * responses with jittered exponential backoff (full-jitter strategy —
  * see `./backoff.ts` for the rationale and AWS Architecture Blog
- * citation).
+ * citation), honoring `Retry-After` on 429s when the server sends it.
  *
  * The wrapper:
  *   - forwards `input`/`init` unchanged to every attempt,
- *   - sleeps before each retry using the configured backoff,
+ *   - sleeps before each retry using the configured backoff — or the
+ *     server's `Retry-After` value verbatim when a 429 carries one
+ *     (no jitter, no clamping; same policy as the SDK's internal
+ *     `withRetry`, see `./retry.ts`),
  *   - retries up to `maxRetries` times (default 3), then returns the
  *     final `Response` (whatever its status) so the caller can
  *     branch on it,
@@ -4025,11 +4055,14 @@ declare function encodeImage(image: VisionInput): Promise<string>;
  * Context-window safety: client-side token estimation and pre-flight overflow
  * warnings for `/api/chat` and `/api/generate`.
  *
- * Why this exists: when `options.num_ctx` is left unset, Ollama loads the
- * model with a conservative default context window (commonly 2048–4096
- * tokens, model-dependent) and **silently truncates** any prompt that doesn't
- * fit — the model just loses the top of the conversation with no error, no
- * warning, and often no visible symptom beyond degraded answers. This module
+ * Why this exists: when `options.num_ctx` is left unset, Ollama sizes the
+ * default context window by available VRAM (4,096 tokens below 24 GiB,
+ * 32,768 at 24–48 GiB, 262,144 at 48 GiB and up; daemon-wide override via
+ * `OLLAMA_CONTEXT_LENGTH`, and cloud models run at their maximum — see the
+ * "Context length" page in the Ollama docs) and **silently truncates** any
+ * prompt that doesn't fit — the model just loses the top of the conversation
+ * with no error, no warning, and often no visible symptom beyond degraded
+ * answers. This module
  * estimates the prompt size client-side (a fast heuristic — no tokenizer
  * download, no model dependency) and surfaces a warning *before* the request
  * is sent, when the estimate approaches the effective context window.
@@ -4098,7 +4131,7 @@ type ContextWindowSource =
 'request'
 /** Client `defaultContextLength` config — injected as `num_ctx` by the pipeline. */
  | 'client-default'
-/** Neither set; Ollama's server default applies (2048–4096, model-dependent). */
+/** Neither set; Ollama's VRAM-tiered server default applies (4k / 32k / 256k). */
  | 'server-fallback';
 /** What the pre-flight check concluded about one request. */
 interface ContextCheck {
@@ -4154,9 +4187,15 @@ declare function checkChatContext(req: ChatRequestOptions, options?: ContextChec
  */
 declare function checkGenerateContext(req: GenerateRequestOptions, options?: ContextCheckOptions): ContextCheck;
 /**
- * The conservative server-side default (2048) Ollama most commonly applies
- * when `num_ctx` is unset — used to warn about *likely* truncation even when
- * no effective window is known client-side.
+ * 2048 — the worst-case floor for the window a daemon allocates when
+ * `num_ctx` is unset, used to warn about *likely* truncation even when no
+ * effective window is known client-side. Deliberately not a prediction:
+ * current daemons tier the unset default by VRAM (4,096 / 32,768 / 262,144
+ * tokens), older daemons defaulted lower, and an admin can pin any value via
+ * `OLLAMA_CONTEXT_LENGTH`. Sizing the floor at the minimum plausible window
+ * keeps this check unable to over-estimate a real window — over-estimation
+ * is the failure that silently re-enables truncation. Use
+ * `client.models.getContextLength()` when the real number matters.
  */
 declare const OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
 /**

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { T as ThinkingMetadata, M as ModelResponse, R as RequestCancellationOptions, S as ShowRequestOptions, a as ShowResponse, P as PullRequestOptions, b as ProgressResponse, c as PushRequestOptions, C as CreateRequestOptions, D as DeleteRequestOptions, d as StatusResponse, e as CopyRequestOptions, f as PsResponse, V as VersionResponse, g as ToolParameters, h as ThinkValue, i as ToolCall, j as ChatRequestOptions, k as ModelOptions, l as ToolDefinition, F as FormatOption, m as ChatResponse, n as Message, G as GenerateRequestOptions, o as GenerateResponse, E as EmbedRequestOptions, p as EmbedResponse, q as EmbeddingsRequestOptions, r as EmbeddingsResponse, W as WebSearchRequestOptions, s as WebSearchResponse, t as WebFetchRequestOptions, u as WebFetchResponse, U as UsageRequestOptions, B as BalanceRequestOptions, v as PingResult, w as VisionInput } from './types-Y3u0FtdN.js';
 export { L as ListResponse, x as Logprob, y as LogprobToken, z as ModelDetails, A as Role, H as ToolCallFunction, I as ToolFunctionDefinition, J as ToolProperty, K as UsageRange, N as UsageScope, O as WebSearchResult, Q as imageStringNeedsResolution, X as resolveImageInput } from './types-Y3u0FtdN.js';
-import { H as HttpClient, F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-DYCxYGG-.js';
-export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NETWORK_ERROR_CODES, r as NOOP_LOGGER, s as NextFunction, t as OllamaAbortError, u as OllamaAgentMaxIterationsError, v as OllamaAgentMaxToolCallsError, w as OllamaAgentToolLoopError, x as OllamaAuthError, y as OllamaBadGatewayError, z as OllamaClientError, J as OllamaClientErrorOptions, K as OllamaErrorRequestContext, Q as OllamaErrorResponseContext, U as OllamaGenericClientError, V as OllamaIncompatibleModelError, W as OllamaMcpError, X as OllamaModelRoutingError, Y as OllamaNetworkError, Z as OllamaNotFoundError, _ as OllamaOverloadedError, $ as OllamaPaymentRequiredError, a0 as OllamaQuotaExceededError, a1 as OllamaRateLimitError, a2 as OllamaRequestTooLargeError, a3 as OllamaRequestValidationError, a4 as OllamaResponseValidationError, a5 as OllamaServerError, a6 as OllamaServerVersionUnknownError, a7 as OllamaSkillInvalidError, a8 as OllamaSkillNotFoundError, a9 as OllamaStreamError, aa as OllamaTimeoutError, ab as OllamaToolTimeoutError, ac as OllamaToolValidationError, ad as OllamaUnsupportedCapabilityError, ae as RequestContext, af as RequestLifecycleEvent, ag as ResponseContext, ah as SseEvent, ai as ThinkingEvent, aj as TokenEvent, ak as ToolCallEvent, al as composeMiddleware, am as createConsoleLogger, an as extractUsage, ao as isNetworkLevelError, ap as mapError, aq as parseSseStream } from './runtime-DYCxYGG-.js';
+import { H as HttpClient, F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-EwyUaNnZ.js';
+export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NETWORK_ERROR_CODES, r as NOOP_LOGGER, s as NextFunction, t as OllamaAbortError, u as OllamaAgentMaxIterationsError, v as OllamaAgentMaxToolCallsError, w as OllamaAgentToolLoopError, x as OllamaAuthError, y as OllamaBadGatewayError, z as OllamaClientError, J as OllamaClientErrorOptions, K as OllamaErrorRequestContext, Q as OllamaErrorResponseContext, U as OllamaGenericClientError, V as OllamaIncompatibleModelError, W as OllamaMcpError, X as OllamaModelRoutingError, Y as OllamaNetworkError, Z as OllamaNotFoundError, _ as OllamaOverloadedError, $ as OllamaPaymentRequiredError, a0 as OllamaQuotaExceededError, a1 as OllamaRateLimitError, a2 as OllamaRequestTooLargeError, a3 as OllamaRequestValidationError, a4 as OllamaResponseValidationError, a5 as OllamaServerError, a6 as OllamaServerVersionUnknownError, a7 as OllamaSkillInvalidError, a8 as OllamaSkillNotFoundError, a9 as OllamaStreamError, aa as OllamaTimeoutError, ab as OllamaToolTimeoutError, ac as OllamaToolValidationError, ad as OllamaUnsupportedCapabilityError, ae as RequestContext, af as RequestLifecycleEvent, ag as ResponseContext, ah as SseEvent, ai as ThinkingEvent, aj as TokenEvent, ak as ToolCallEvent, al as composeMiddleware, am as createConsoleLogger, an as extractUsage, ao as isNetworkLevelError, ap as mapError, aq as parseRetryAfterMs, ar as parseSseStream } from './runtime-EwyUaNnZ.js';
 import { z } from 'zod';
-import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-CAvwqIjx.js';
-export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as OllamaOpenAIChatContentPart, a4 as OllamaOpenAIChatMessage, a5 as OllamaOpenAICompletionRequest, a6 as OllamaOpenAIEmbeddingRequest, a7 as OllamaOpenAIImageDataUrl, a8 as OllamaOpenAIReasoningEffort, a9 as OllamaOpenAIResponsesRequest, aa as OpenAIChatCompletionChoice, b as OpenAIChatCompletionChunk, ab as OpenAIChatCompletionChunkChoice, ac as OpenAIChatCompletionDelta, O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, ad as OpenAIChatCompletionStream, ae as OpenAICompletionChoice, e as OpenAICompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, af as OpenAICompletionStream, ag as OpenAIContentPart, ah as OpenAIEmbeddingInput, ai as OpenAIEmbeddingItem, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, aj as OpenAIFunctionDefinition, ak as OpenAIImageUrlContentPart, h as OpenAIListModelsResponse, al as OpenAIMessage, i as OpenAIModelItem, am as OpenAIReasoningEffort, an as OpenAIResponseFormat, ao as OpenAIResponsesCompletedEvent, ap as OpenAIResponsesContentPartAddedEvent, aq as OpenAIResponsesContentPartDoneEvent, ar as OpenAIResponsesCreatedEvent, as as OpenAIResponsesError, at as OpenAIResponsesEventBase, au as OpenAIResponsesFailedEvent, av as OpenAIResponsesFunctionCallArgumentsDeltaEvent, aw as OpenAIResponsesFunctionCallArgumentsDoneEvent, ax as OpenAIResponsesInProgressEvent, ay as OpenAIResponsesIncompleteDetails, az as OpenAIResponsesIncompleteEvent, aA as OpenAIResponsesOutputContent, aB as OpenAIResponsesOutputFunctionCall, aC as OpenAIResponsesOutputItem, aD as OpenAIResponsesOutputItemAddedEvent, aE as OpenAIResponsesOutputItemDoneEvent, aF as OpenAIResponsesOutputMessage, aG as OpenAIResponsesOutputReasoning, aH as OpenAIResponsesOutputRefusal, aI as OpenAIResponsesOutputTextContent, aJ as OpenAIResponsesOutputTextDeltaEvent, aK as OpenAIResponsesOutputTextDoneEvent, aL as OpenAIResponsesQueuedEvent, aM as OpenAIResponsesReasoningSummaryPartAddedEvent, aN as OpenAIResponsesReasoningSummaryPartDoneEvent, aO as OpenAIResponsesReasoningSummaryTextDeltaEvent, aP as OpenAIResponsesReasoningSummaryTextDoneEvent, aQ as OpenAIResponsesReasoningTextDeltaEvent, aR as OpenAIResponsesReasoningTextDoneEvent, aS as OpenAIResponsesRefusalDeltaEvent, aT as OpenAIResponsesRefusalDoneEvent, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, aU as OpenAIResponsesStatus, aV as OpenAIResponsesStream, aW as OpenAIResponsesStreamError, l as OpenAIResponsesStreamEvent, aX as OpenAIResponsesUsage, aY as OpenAIStreamOptions, aZ as OpenAITextContentPart, a_ as OpenAITool, a$ as OpenAIToolCall, b0 as OpenAIToolCallDelta, b1 as OpenAIUsage, b2 as SystemOneConfidence, b3 as SystemOneProbabilities } from './anthropic-CAvwqIjx.js';
+import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-BmFk4Pjq.js';
+export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as OllamaOpenAIChatContentPart, a4 as OllamaOpenAIChatMessage, a5 as OllamaOpenAICompletionRequest, a6 as OllamaOpenAIEmbeddingRequest, a7 as OllamaOpenAIImageDataUrl, a8 as OllamaOpenAIReasoningEffort, a9 as OllamaOpenAIResponsesRequest, aa as OpenAIChatCompletionChoice, b as OpenAIChatCompletionChunk, ab as OpenAIChatCompletionChunkChoice, ac as OpenAIChatCompletionDelta, O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, ad as OpenAIChatCompletionStream, ae as OpenAICompletionChoice, e as OpenAICompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, af as OpenAICompletionStream, ag as OpenAIContentPart, ah as OpenAIEmbeddingInput, ai as OpenAIEmbeddingItem, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, aj as OpenAIFunctionDefinition, ak as OpenAIImageUrlContentPart, h as OpenAIListModelsResponse, al as OpenAIMessage, i as OpenAIModelItem, am as OpenAIReasoningEffort, an as OpenAIResponseFormat, ao as OpenAIResponsesCompletedEvent, ap as OpenAIResponsesContentPartAddedEvent, aq as OpenAIResponsesContentPartDoneEvent, ar as OpenAIResponsesCreatedEvent, as as OpenAIResponsesError, at as OpenAIResponsesEventBase, au as OpenAIResponsesFailedEvent, av as OpenAIResponsesFunctionCallArgumentsDeltaEvent, aw as OpenAIResponsesFunctionCallArgumentsDoneEvent, ax as OpenAIResponsesInProgressEvent, ay as OpenAIResponsesIncompleteDetails, az as OpenAIResponsesIncompleteEvent, aA as OpenAIResponsesOutputContent, aB as OpenAIResponsesOutputFunctionCall, aC as OpenAIResponsesOutputItem, aD as OpenAIResponsesOutputItemAddedEvent, aE as OpenAIResponsesOutputItemDoneEvent, aF as OpenAIResponsesOutputMessage, aG as OpenAIResponsesOutputReasoning, aH as OpenAIResponsesOutputRefusal, aI as OpenAIResponsesOutputTextContent, aJ as OpenAIResponsesOutputTextDeltaEvent, aK as OpenAIResponsesOutputTextDoneEvent, aL as OpenAIResponsesQueuedEvent, aM as OpenAIResponsesReasoningSummaryPartAddedEvent, aN as OpenAIResponsesReasoningSummaryPartDoneEvent, aO as OpenAIResponsesReasoningSummaryTextDeltaEvent, aP as OpenAIResponsesReasoningSummaryTextDoneEvent, aQ as OpenAIResponsesReasoningTextDeltaEvent, aR as OpenAIResponsesReasoningTextDoneEvent, aS as OpenAIResponsesRefusalDeltaEvent, aT as OpenAIResponsesRefusalDoneEvent, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, aU as OpenAIResponsesStatus, aV as OpenAIResponsesStream, aW as OpenAIResponsesStreamError, l as OpenAIResponsesStreamEvent, aX as OpenAIResponsesUsage, aY as OpenAIStreamOptions, aZ as OpenAITextContentPart, a_ as OpenAITool, a$ as OpenAIToolCall, b0 as OpenAIToolCallDelta, b1 as OpenAIUsage, b2 as SystemOneConfidence, b3 as SystemOneProbabilities } from './anthropic-BmFk4Pjq.js';
 import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-75UFDzOO.js';
 export { d as AppliedSkillResult, e as ApplySkillOptions, P as ParsedFrontmatter, S as Skill, f as SkillFrontmatter, g as SkillSummary, h as ToolExecutionContext, i as ToolExecutionFailure, j as ToolExecutionSuccess, k as ToolRegistryOptions, l as applySkill, p as parseFrontmatter } from './compose-75UFDzOO.js';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.js';
@@ -219,7 +219,10 @@ declare function listAvailableModels(http: HttpClient): Promise<ModelResponse[]>
  * Dynamic context-window discovery.
  *
  * Guessing context windows ("it's probably 2048… or 4096?") is how silent
- * truncation happens. Ollama advertises the real numbers in two places, and
+ * truncation happens — and current daemons make the guess worse, not better:
+ * the unset-`num_ctx` default is tiered by VRAM (4k / 32k / 256k), so a
+ * hardcoded assumption is now wrong in both directions. Ollama advertises
+ * the real numbers in two places, and
  * they answer *different questions*:
  *
  *   - **`GET /api/ps`** reports `context_length` for every currently-running
@@ -262,14 +265,14 @@ type ContextLengthSource =
  | 'parameters'
 /** `POST /api/show` `model_info["*.context_length"]` — native GGUF maximum. */
  | 'model-info'
-/** Nothing discoverable — Ollama's conservative unset-`num_ctx` default (2048). */
+/** Nothing discoverable — the 2048 worst-case floor for the unset-`num_ctx` window (current daemons tier by VRAM: 4k / 32k / 256k). */
  | 'fallback';
 /** Result of {@link ModelsClient.getContextLength}. */
 interface DiscoveredContextLength {
     /**
      * The effective context window to program against, resolved by precedence:
      * `running` (exact, when loaded) → `parameters` (Modelfile default) →
-     * `model-info` (native max) → `2048` fallback.
+     * `model-info` (native max) → worst-case `2048` fallback.
      */
     readonly contextLength: number;
     /** Which source produced {@link contextLength}. */
@@ -329,7 +332,9 @@ interface ContextLengthSignals {
  *      (Ollama's conservative default), so native is a *ceiling*, not an
  *      expectation.
  *   4. **Fallback** — {@link OLLAMA_FALLBACK_CONTEXT_LENGTH} (2048), the
- *      conservative server-side default, so the result is always actionable.
+ *      worst-case floor for the unset-`num_ctx` window (current daemons tier
+ *      by VRAM up to 262,144), so the result is always actionable and can
+ *      never over-estimate a real window.
  *
  * Pure — used by `ModelsClient.getContextLength()` and exported for callers
  * that already hold `/api/ps` / `/api/show` responses.
@@ -363,6 +368,13 @@ interface RetryConfig {
 declare const DEFAULT_RETRY_CONFIG: RetryConfig;
 /**
  * Executes an async operation with retries according to config.
+ *
+ * Retry pacing: a 429 whose `Retry-After` header produced
+ * `OllamaRateLimitError.retryAfterMs` sleeps exactly that long before the
+ * next attempt (server authority — see {@link retryDelayMs}); all other
+ * retryable errors sleep a full-jitter exponential backoff. The delay
+ * actually used is reported to `onRetry` either way, and remains abortable
+ * through `signal` for the whole wait.
  */
 declare function withRetry<T>(operation: (attempt: number) => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
 
@@ -758,9 +770,11 @@ interface OllamaClientConfig {
      * Default context window (`num_ctx`) applied to every `chat`/`generate`
      * request that doesn't set `options.num_ctx` itself. Injected as
      * `options.num_ctx` on the wire, making the effective window explicit
-     * instead of leaving it to Ollama's server default (commonly 2048–4096,
-     * model-dependent) — which **silently truncates** prompts that don't fit,
-     * with no error and no warning. See `src/context-safety.ts`.
+     * instead of leaving it to Ollama's VRAM-tiered server default (4,096
+     * tokens below 24 GiB, 32,768 at 24–48 GiB, 262,144 at 48 GiB and up;
+     * daemon-wide override via `OLLAMA_CONTEXT_LENGTH`) — which **silently
+     * truncates** prompts that don't fit, with no error and no warning. See
+     * `src/context-safety.ts`.
      */
     readonly defaultContextLength?: number;
     /**
@@ -887,7 +901,8 @@ declare class ModelsClient {
     ps(request?: RequestCancellationOptions): Promise<PsResponse>;
     /**
      * 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
@@ -899,7 +914,7 @@ declare class ModelsClient {
      *   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
@@ -1378,8 +1393,8 @@ declare function sanitizeHistoryForNextTurn(messages: readonly Message[], option
 interface SessionCompactionOptions {
     /**
      * Token budget for the compacted history. Defaults to the session's own
-     * window: `options.num_ctx` from the session config, or Ollama's
-     * conservative 2048 fallback when unset — pair with
+     * window: `options.num_ctx` from the session config, or the 2048
+     * worst-case fallback when unset — pair with
      * `client.models.getContextLength()` to program against the real window.
      */
     readonly maxEstimatedTokens?: number | undefined;
@@ -2436,7 +2451,9 @@ declare 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).
      */
     webSearch(req: WebSearchRequestOptions): Promise<WebSearchResponse>;
     /**
@@ -2451,8 +2468,11 @@ declare 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.
      *
@@ -2472,7 +2492,9 @@ declare 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();
@@ -2584,8 +2606,11 @@ declare function createTimeoutSignal(timeoutMs?: number, userSignal?: AbortSigna
  * fan-out embed batches, speculative-decoding pipelines) can't always
  * predict saturation ahead of time, so the SDK exposes this helper —
  * a thin wrapper around `fetch` that retries 503/429 responses with
- * the same jittered exponential backoff used by the SDK's internal
- * transport (see `./backoff.ts` and `./retry.ts`).
+ * the same retry discipline used by the SDK's internal transport (see
+ * `./backoff.ts` and `./retry.ts`): jittered exponential backoff, except
+ * that a 429 carrying `Retry-After` (RFC 9110 § 10.2.3) is honored
+ * verbatim — the server said when to retry, and sleeping less than that
+ * would only compound the rate limiting.
  *
  * The helper is intentionally standalone: it works with any
  * `fetch`-shaped function (browser `globalThis.fetch`, `undici`, an
@@ -2624,8 +2649,10 @@ interface FetchWithBackoffConfig {
      *
      * Receives the attempt index (0-based for the original request,
      * 1+ for retries), the HTTP status that triggered the retry
-     * (or `0` for network-level failures), and the calculated delay
-     * in milliseconds (already jittered).
+     * (or `0` for network-level failures), and the delay
+     * in milliseconds that will be slept (the server's `Retry-After`
+     * verbatim on a 429 that carried one; otherwise the jittered
+     * backoff sample).
      */
     readonly onRetry?: ((attempt: number, status: number, delayMs: number) => void) | undefined;
     /**
@@ -2667,11 +2694,14 @@ declare const DEFAULT_FETCH_BACKOFF_CONFIG: {
  * Wrapper around any `fetch`-shaped function that retries HTTP 429 / 503
  * responses with jittered exponential backoff (full-jitter strategy —
  * see `./backoff.ts` for the rationale and AWS Architecture Blog
- * citation).
+ * citation), honoring `Retry-After` on 429s when the server sends it.
  *
  * The wrapper:
  *   - forwards `input`/`init` unchanged to every attempt,
- *   - sleeps before each retry using the configured backoff,
+ *   - sleeps before each retry using the configured backoff — or the
+ *     server's `Retry-After` value verbatim when a 429 carries one
+ *     (no jitter, no clamping; same policy as the SDK's internal
+ *     `withRetry`, see `./retry.ts`),
  *   - retries up to `maxRetries` times (default 3), then returns the
  *     final `Response` (whatever its status) so the caller can
  *     branch on it,
@@ -4025,11 +4055,14 @@ declare function encodeImage(image: VisionInput): Promise<string>;
  * Context-window safety: client-side token estimation and pre-flight overflow
  * warnings for `/api/chat` and `/api/generate`.
  *
- * Why this exists: when `options.num_ctx` is left unset, Ollama loads the
- * model with a conservative default context window (commonly 2048–4096
- * tokens, model-dependent) and **silently truncates** any prompt that doesn't
- * fit — the model just loses the top of the conversation with no error, no
- * warning, and often no visible symptom beyond degraded answers. This module
+ * Why this exists: when `options.num_ctx` is left unset, Ollama sizes the
+ * default context window by available VRAM (4,096 tokens below 24 GiB,
+ * 32,768 at 24–48 GiB, 262,144 at 48 GiB and up; daemon-wide override via
+ * `OLLAMA_CONTEXT_LENGTH`, and cloud models run at their maximum — see the
+ * "Context length" page in the Ollama docs) and **silently truncates** any
+ * prompt that doesn't fit — the model just loses the top of the conversation
+ * with no error, no warning, and often no visible symptom beyond degraded
+ * answers. This module
  * estimates the prompt size client-side (a fast heuristic — no tokenizer
  * download, no model dependency) and surfaces a warning *before* the request
  * is sent, when the estimate approaches the effective context window.
@@ -4098,7 +4131,7 @@ type ContextWindowSource =
 'request'
 /** Client `defaultContextLength` config — injected as `num_ctx` by the pipeline. */
  | 'client-default'
-/** Neither set; Ollama's server default applies (2048–4096, model-dependent). */
+/** Neither set; Ollama's VRAM-tiered server default applies (4k / 32k / 256k). */
  | 'server-fallback';
 /** What the pre-flight check concluded about one request. */
 interface ContextCheck {
@@ -4154,9 +4187,15 @@ declare function checkChatContext(req: ChatRequestOptions, options?: ContextChec
  */
 declare function checkGenerateContext(req: GenerateRequestOptions, options?: ContextCheckOptions): ContextCheck;
 /**
- * The conservative server-side default (2048) Ollama most commonly applies
- * when `num_ctx` is unset — used to warn about *likely* truncation even when
- * no effective window is known client-side.
+ * 2048 — the worst-case floor for the window a daemon allocates when
+ * `num_ctx` is unset, used to warn about *likely* truncation even when no
+ * effective window is known client-side. Deliberately not a prediction:
+ * current daemons tier the unset default by VRAM (4,096 / 32,768 / 262,144
+ * tokens), older daemons defaulted lower, and an admin can pin any value via
+ * `OLLAMA_CONTEXT_LENGTH`. Sizing the floor at the minimum plausible window
+ * keeps this check unable to over-estimate a real window — over-estimation
+ * is the failure that silently re-enables truncation. Use
+ * `client.models.getContextLength()` when the real number matters.
  */
 declare const OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
 /**