@nemesis-oss/ollama-sdk 1.15.0 → 1.17.0

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-DbPnfVh-.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-DbPnfVh-.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-C4RRHqOs.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 NOOP_LOGGER, r as NextFunction, s as OllamaAbortError, t as OllamaAgentMaxIterationsError, u as OllamaAgentMaxToolCallsError, v as OllamaAgentToolLoopError, w as OllamaAuthError, x as OllamaBadGatewayError, y as OllamaClientError, z as OllamaClientErrorOptions, J as OllamaErrorRequestContext, K as OllamaErrorResponseContext, Q as OllamaGenericClientError, U as OllamaIncompatibleModelError, V as OllamaMcpError, W as OllamaModelRoutingError, X as OllamaNetworkError, Y as OllamaNotFoundError, Z as OllamaOverloadedError, _ as OllamaQuotaExceededError, $ as OllamaRateLimitError, a0 as OllamaRequestTooLargeError, a1 as OllamaRequestValidationError, a2 as OllamaResponseValidationError, a3 as OllamaServerError, a4 as OllamaServerVersionUnknownError, a5 as OllamaSkillInvalidError, a6 as OllamaSkillNotFoundError, a7 as OllamaStreamError, a8 as OllamaTimeoutError, a9 as OllamaToolTimeoutError, aa as OllamaToolValidationError, ab as OllamaUnsupportedCapabilityError, ac as RequestContext, ad as RequestLifecycleEvent, ae as ResponseContext, af as SseEvent, ag as ThinkingEvent, ah as TokenEvent, ai as ToolCallEvent, aj as composeMiddleware, ak as createConsoleLogger, al as extractUsage, am as mapError, an as parseSseStream } from './runtime-C4RRHqOs.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-CdZP-N7j.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 OllamaQuotaExceededError, a0 as OllamaRateLimitError, a1 as OllamaRequestTooLargeError, a2 as OllamaRequestValidationError, a3 as OllamaResponseValidationError, a4 as OllamaServerError, a5 as OllamaServerVersionUnknownError, a6 as OllamaSkillInvalidError, a7 as OllamaSkillNotFoundError, a8 as OllamaStreamError, a9 as OllamaTimeoutError, aa as OllamaToolTimeoutError, ab as OllamaToolValidationError, ac as OllamaUnsupportedCapabilityError, ad as RequestContext, ae as RequestLifecycleEvent, af as ResponseContext, ag as SseEvent, ah as ThinkingEvent, ai as TokenEvent, aj as ToolCallEvent, ak as composeMiddleware, al as createConsoleLogger, am as extractUsage, an as isNetworkLevelError, ao as mapError, ap as parseSseStream } from './runtime-CdZP-N7j.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-UeaVjLeP.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-UeaVjLeP.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-AKbXnWJU.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-AKbXnWJU.cjs';
 import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-DFkmtUOP.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-DFkmtUOP.cjs';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.cjs';
@@ -970,8 +970,8 @@ declare class ModelsClient {
      * model-not-found (404), or VRAM-exhaustion failures.
      */
     pin(model: string): Promise<void>;
-    createBlob(digest: string, data: BinaryBody): Promise<void>;
-    checkBlob(digest: string): Promise<boolean>;
+    createBlob(digest: string, data: BinaryBody, request?: RequestCancellationOptions): Promise<void>;
+    checkBlob(digest: string, request?: RequestCancellationOptions): Promise<boolean>;
     /**
      * Computes a blob digest the way Ollama's content-addressed store expects:
      * SHA-256 over the raw bytes, formatted as `sha256:<64 lowercase hex>`.
@@ -992,17 +992,44 @@ declare class ModelsClient {
      */
     createBlobFromData(data: Uint8Array, opts?: {
         readonly digest?: string | undefined;
-        readonly signal?: AbortSignal | undefined;
-    }): Promise<BlobUploadResult>;
+    } & RequestCancellationOptions): Promise<BlobUploadResult>;
+    /**
+     * Streams a blob upload straight from a web `ReadableStream` — the
+     * multi-gigabyte-safe counterpart of {@link createBlobFromData}. The body
+     * is never materialized in memory: the transport hands the stream to
+     * `fetch` directly (setting `duplex: 'half'`, which Node 18+ requires for
+     * stream bodies), so peak heap usage is a transport-level chunk, not the
+     * blob size.
+     *
+     * The digest must be known up front — it *is* the upload URL
+     * (`/api/blobs/<digest>`), the same content-addressed protocol
+     * `curl -T` performs. Hash first when you don't have it: in-memory bytes
+     * via {@link computeBlobDigest}, files via {@link createBlobFromFile}
+     * (which hashes in a streaming pass). The server verifies the streamed
+     * bytes against the digest and rejects mismatches, so a corrupted or
+     * truncated stream fails the upload instead of poisoning the store.
+     */
+    createBlobFromStream(digest: string, stream: ReadableStream<Uint8Array>, request?: RequestCancellationOptions): Promise<BlobUploadResult>;
     /**
      * 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.
+     *
+     * Streams both passes in fixed-size chunks — peak heap is O(chunk), not
+     * O(file), so multi-gigabyte GGUFs never enter the Node heap:
+     *
+     *  1. **Hash pass** (skipped when `opts.digest` is provided): the file is
+     *     streamed through `node:crypto`'s incremental SHA-256.
+     *  2. **Upload pass**: `node:fs` createReadStream → web ReadableStream →
+     *     `fetch` body with `duplex: 'half'` (see {@link createBlobFromStream}).
+     *
+     * A pre-existing blob (HEAD 200) skips the upload pass entirely, same as
+     * {@link createBlobFromData}.
      */
     createBlobFromFile(path: string, opts?: {
-        readonly signal?: AbortSignal | undefined;
-    }): Promise<BlobUploadResult & {
+        readonly digest?: string | undefined;
+    } & RequestCancellationOptions): Promise<BlobUploadResult & {
         readonly fileName: string;
     }>;
     /**
@@ -2277,8 +2304,8 @@ declare class OllamaClient {
      */
     readonly getContextLength: (request: ContextDiscoveryRequestOptions) => Promise<DiscoveredContextLength>;
     readonly version: () => Promise<VersionResponse>;
-    readonly createBlob: (digest: string, data: BinaryBody) => Promise<void>;
-    readonly checkBlob: (digest: string) => Promise<boolean>;
+    readonly createBlob: (digest: string, data: BinaryBody, request?: RequestCancellationOptions) => Promise<void>;
+    readonly checkBlob: (digest: string, request?: RequestCancellationOptions) => Promise<boolean>;
     /**
      * Immediately unloads `model` from VRAM. Convenience alias for
      * {@link ModelsClient.unload} — see that method for the full
@@ -2780,6 +2807,140 @@ declare function toDataStream<TChunk, TFinal>(stream: OllamaStream<TChunk, TFina
  */
 declare function toResponse<TChunk, TFinal>(stream: OllamaStream<TChunk, TFinal>, init?: ResponseInit): Response;
 
+/**
+ * Zero-copy stream observation — the safe alternative to `ReadableStream.tee()`
+ * for multi-sink consumption (audit logging, token counting, telemetry taps).
+ *
+ * ## The `tee()` hazard this exists for
+ *
+ * Developers streaming to a UI while also feeding a logger (or a token
+ * counter, or an OpenTelemetry exporter) typically reach for:
+ *
+ * ```ts
+ * // VULNERABLE PATTERN — do not do this
+ * const [forUi, forLogger] = response.body.tee();
+ * ```
+ *
+ * WHATWG `tee()` branches share a single upstream pull mechanism: a branch
+ * that reads slower than its sibling forces every intermediate chunk to be
+ * retained in that branch's internal queue until it catches up. If the slow
+ * consumer is a logger waiting on a database write — or never drains at all —
+ * the queue grows without bound, and because both branches apply shared
+ * backpressure, the *fast* consumer is throttled by the slowest one. In a
+ * long-lived streaming server this is a slow, silent heap leak.
+ *
+ * ## What `observeStream` does instead
+ *
+ * A single-pass wrapper: chunks flow from the source through the observer
+ * callbacks to the primary consumer with **no second queue and no forked
+ * stream**. The contract is deliberately one-sided in favor of the primary
+ * consumer:
+ *
+ *   - **Never blocks.** Observer callbacks run on a serialized microtask
+ *     chain, not on the hot path. A slow async observer (a logger waiting on
+ *     I/O) delays only its own tail — the primary consumer keeps receiving
+ *     chunks at source speed.
+ *   - **Never fails.** An observer that throws (sync) or rejects (async) is
+ *     routed to `onListenerError` and otherwise discarded. Observer failures
+ *     can never poison the primary pipeline.
+ *   - **Never leaks via the wrapper.** There is no second branch to
+ *     backpressure. The only retained state is one closure per backlogged
+ *     observer callback; if your observer can stall *forever*, bound it on
+ *     your side (queue, drop policy) — the wrapper will keep enqueueing
+ *     otherwise, exactly like any fire-and-forget log sink.
+ *   - **Ordered.** Observer callbacks run strictly FIFO, one at a time —
+ *     async sinks see chunks in stream order, and `onDone` is enqueued only
+ *     after the last chunk's callback settles. (This is intentionally
+ *     stricter than a naive `void onChunk(chunk)` fire-and-forget, which
+ *     runs concurrent, out-of-order observers and turns a rejected async
+ *     callback into an unhandled rejection.)
+ *
+ * ## Lifecycle
+ *
+ *   - Source completes naturally → `onDone` (enqueued after the last chunk
+ *     callback settles, so a logger has flushed everything it saw).
+ *   - Source throws → `onError(err)` immediately, then the error re-throws to
+ *     the primary consumer (the observer is transparent, not a circuit
+ *     breaker).
+ *   - Primary consumer stops early (`break` / `return` / `throw` inside the
+ *     `for await` loop) → `onAbandon()` immediately. This is distinct from
+ *     completion: the source's iterator-`return()` has already closed the
+ *     underlying transport by the time `onAbandon` fires.
+ *
+ * Works over any `AsyncIterable<T>` — the SDK's `OllamaStream` (streaming
+ * `chat`/`generate`), the raw NDJSON chunk iterables, or your own sources.
+ * Note that `OllamaStream` itself is dual-mode but mode-exclusive (`.on()`
+ * listeners cannot be combined with `for await`); `observeStream` is the
+ * supported way to tap a stream you are already iterating.
+ */
+/**
+ * Lifecycle phase an observer failure came from. `'chunk'` and `'done'`
+ * failures arrive from the serialized callback chain; `'error'` and
+ * `'abandon'` failures come from those terminal hooks themselves.
+ */
+type StreamObserverPhase = 'chunk' | 'done' | 'error' | 'abandoned';
+/** Passive, best-effort observer hooks — see the module docs for semantics. */
+interface StreamObserverCallbacks<T> {
+    /**
+     * Called once per chunk, in stream order, FIFO, never overlapping with a
+     * previous still-running call. May be sync (`void`) or async
+     * (`Promise<void>`); async return values are awaited *on the observer
+     * chain only* — they never delay the primary consumer. Rejections (and
+     * sync throws) route to {@link StreamObserverCallbacks.onListenerError}.
+     */
+    onChunk?: ((chunk: T) => void | Promise<void>) | undefined;
+    /**
+     * Called with the source's error immediately before that error is re-thrown
+     * to the primary consumer. A throwing `onError` hook cannot mask the
+     * original error — it is reported via {@link StreamObserverCallbacks.onListenerError}
+     * and the original error still propagates.
+     */
+    onError?: ((error: unknown) => void) | undefined;
+    /**
+     * Called when the source completes naturally — enqueued after the last
+     * chunk's observer callback settles, so a flushed logger has seen every
+     * chunk before its "done" marker.
+     */
+    onDone?: (() => void | Promise<void>) | undefined;
+    /**
+     * Called when the primary consumer stops early (`break`/`return`/`throw` in
+     * the consuming loop). The source has already been closed via the
+     * iterator-`return()` protocol when this fires. `onDone` does not fire in
+     * this case.
+     */
+    onAbandon?: (() => void) | undefined;
+    /**
+     * The observation failure channel: any observer hook that throws or rejects
+     * is reported here together with the phase it came from, and then
+     * discarded. If this hook itself throws, the failure is swallowed — an
+     * error reporter must never become the next unhandled rejection.
+     */
+    onListenerError?: ((error: unknown, phase: StreamObserverPhase) => void) | undefined;
+}
+/**
+ * Wraps an `AsyncIterable` with passive observer hooks without creating a
+ * secondary buffered stream queue — avoiding the memory retention and shared
+ * backpressure penalties of `ReadableStream.tee()`.
+ *
+ * @example
+ * ```ts
+ * const stream = await client.chat({ model: 'llama4', messages, stream: true });
+ * let tokens = 0;
+ * const observed = observeStream(stream, {
+ *   onChunk: (event) => {
+ *     if (event.type === 'token') tokens += 1;
+ *     auditLog.write(event); // slow async sink — never delays the consumer
+ *   },
+ *   onDone: () => auditLog.flush(),
+ *   onListenerError: (err) => telemetry.count('audit_log_failure', err),
+ * });
+ * for await (const event of observed) {
+ *   ui.render(event); // primary consumer — full speed, full order
+ * }
+ * ```
+ */
+declare function observeStream<T>(source: AsyncIterable<T>, callbacks?: StreamObserverCallbacks<T>): AsyncGenerator<T, void, unknown>;
+
 /**
  * Client-side usage budgeting.
  *
@@ -3695,7 +3856,33 @@ interface ContextCheck {
     readonly windowSource: ContextWindowSource;
     /** True when the estimate crossed the warning threshold of the effective window. */
     readonly exceedsThreshold: boolean;
+    /**
+     * Present only when `exceedsThreshold` is `true`: the smallest power-of-two
+     * window with ~30% generation headroom above the estimate (see
+     * {@link recommendContextWindow}). A starting point, not a verdict — check
+     * the model's native ceiling with `client.models.getContextLength()` before
+     * adopting it; a prompt that outgrows the native maximum needs compaction
+     * or history truncation, not a bigger `num_ctx`.
+     */
+    readonly recommendedNumCtx?: number | undefined;
 }
+/**
+ * Smallest power-of-two context window that comfortably fits
+ * `estimatedTokens` — ~30% headroom for the response, floored at 4096 (the
+ * common modern server default when `num_ctx` is unset).
+ *
+ * Uses an exact doubling loop rather than
+ * `Math.pow(2, Math.ceil(Math.log2(x)))`: floating-point `log2` of exact
+ * powers of two can land marginally above the integer (e.g.
+ * `Math.log2(8) > 3` on some platforms), which rounds a perfect fit *up* a
+ * whole power of two. The loop has no such boundary bugs.
+ *
+ * Non-finite / non-positive inputs return the 4096 floor rather than throwing:
+ * callers use this to *suggest* a window after their own estimate already
+ * flagged a problem, so garbage-in should degrade to a conservative
+ * suggestion, not a second error path.
+ */
+declare function recommendContextWindow(estimatedTokens: number): number;
 interface ContextCheckOptions {
     /** Client `defaultContextLength`, applied when the request doesn't set `num_ctx`. */
     readonly defaultContextLength?: number | undefined;
@@ -3862,4 +4049,4 @@ declare class ModelAffinityScheduler {
 /** Convenience factory — `createModelAffinityScheduler(client, opts)` reads better in setups. */
 declare function createModelAffinityScheduler(client: ModelAffinityClient | OllamaClient, options?: ModelAffinitySchedulerOptions): ModelAffinityScheduler;
 
-export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, AbortableAsyncIterable, type AffinityRunningModel, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, BalanceRequestOptions, type BalanceResponse, type BlobUploadResult, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, type CompactionOptions, type CompareDraftPerformanceOptions, type ContextCheck, type ContextCheckOptions, type ContextDiscoveryRequestOptions, type ContextLengthSignals, type ContextLengthSource, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, type CreateModelFromGgufOptions, CreateRequestOptions, type CumulativeCacheStats, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, type DefineToolOptions, DeleteRequestOptions, type DiscoveredContextLength, type DraftBenchmarkClient, type DraftPerformanceComparison, type DraftRunStats, type EmbedBatchOptions, type EmbedBatchResult, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, type FormattedTelemetry, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, type HistorySanitizeOptions, HttpClient, IMAGE_TOKEN_ESTIMATE, type IncludedBalance, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, type KeepAlive, type KnownDoneReason, type LegacyBalanceLimit, type LegacyIncludedBalance, type LoadMcpToolsOptions, Logger, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelAffinityClient, ModelAffinityRouter, type ModelAffinityRoutingOptions, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, type ModelAffinitySnapshot, type ModelAffinityStats, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, type OversizedEmbedInput, type ParallelToolCallBehavior, PingResult, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, type RawOllamaMetrics, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, type SessionCompactionOptions, type SessionCompactionResult, type SessionTurn, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type SupportedSchema, type SystemOneAnswer, type SystemOneAnswers, SystemOneChoiceAnswer, SystemOneChoiceQuestion, SystemOneContent, SystemOneNoulAnswer, SystemOneNoulQuestion, type SystemOneQuestion, type SystemOneQuestions, type SystemOneRequest, type SystemOneResponse, SystemOneScoreAnswer, SystemOneScoreQuestion, type SystemOneUsage, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolCallAccumulator, ToolDefinition, ToolExecutionResult, ToolHandler, ToolParameters, ToolRegistry, type TurnCacheStats, type UsageBucket, type UsageMetrics, UsageRequestOptions, type UsageResponse, VersionResponse, VisionInput, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchRequestOptions, WebFetchResponse, type WebFetchToolParams, WebSearchRequestOptions, WebSearchResponse, type WebSearchToolParams, type WebToolsClient, type WebToolsOptions, addSpanEvent, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, compareDraftPerformance, contextWarningMessage, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
+export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, AbortableAsyncIterable, type AffinityRunningModel, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, BalanceRequestOptions, type BalanceResponse, type BlobUploadResult, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, type CompactionOptions, type CompareDraftPerformanceOptions, type ContextCheck, type ContextCheckOptions, type ContextDiscoveryRequestOptions, type ContextLengthSignals, type ContextLengthSource, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, type CreateModelFromGgufOptions, CreateRequestOptions, type CumulativeCacheStats, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, type DefineToolOptions, DeleteRequestOptions, type DiscoveredContextLength, type DraftBenchmarkClient, type DraftPerformanceComparison, type DraftRunStats, type EmbedBatchOptions, type EmbedBatchResult, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, type FormattedTelemetry, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, type HistorySanitizeOptions, HttpClient, IMAGE_TOKEN_ESTIMATE, type IncludedBalance, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, type KeepAlive, type KnownDoneReason, type LegacyBalanceLimit, type LegacyIncludedBalance, type LoadMcpToolsOptions, Logger, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelAffinityClient, ModelAffinityRouter, type ModelAffinityRoutingOptions, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, type ModelAffinitySnapshot, type ModelAffinityStats, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, type OversizedEmbedInput, type ParallelToolCallBehavior, PingResult, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, type RawOllamaMetrics, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, type SessionCompactionOptions, type SessionCompactionResult, type SessionTurn, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type StreamObserverCallbacks, type StreamObserverPhase, type SupportedSchema, type SystemOneAnswer, type SystemOneAnswers, SystemOneChoiceAnswer, SystemOneChoiceQuestion, SystemOneContent, SystemOneNoulAnswer, SystemOneNoulQuestion, type SystemOneQuestion, type SystemOneQuestions, type SystemOneRequest, type SystemOneResponse, SystemOneScoreAnswer, SystemOneScoreQuestion, type SystemOneUsage, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolCallAccumulator, ToolDefinition, ToolExecutionResult, ToolHandler, ToolParameters, ToolRegistry, type TurnCacheStats, type UsageBucket, type UsageMetrics, UsageRequestOptions, type UsageResponse, VersionResponse, VisionInput, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchRequestOptions, WebFetchResponse, type WebFetchToolParams, WebSearchRequestOptions, WebSearchResponse, type WebSearchToolParams, type WebToolsClient, type WebToolsOptions, addSpanEvent, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, compareDraftPerformance, contextWarningMessage, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, observeStream, parseNdjsonStream, parseStructuredOutput, recommendContextWindow, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };

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-DbPnfVh-.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-DbPnfVh-.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-BIjr5ME4.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 NOOP_LOGGER, r as NextFunction, s as OllamaAbortError, t as OllamaAgentMaxIterationsError, u as OllamaAgentMaxToolCallsError, v as OllamaAgentToolLoopError, w as OllamaAuthError, x as OllamaBadGatewayError, y as OllamaClientError, z as OllamaClientErrorOptions, J as OllamaErrorRequestContext, K as OllamaErrorResponseContext, Q as OllamaGenericClientError, U as OllamaIncompatibleModelError, V as OllamaMcpError, W as OllamaModelRoutingError, X as OllamaNetworkError, Y as OllamaNotFoundError, Z as OllamaOverloadedError, _ as OllamaQuotaExceededError, $ as OllamaRateLimitError, a0 as OllamaRequestTooLargeError, a1 as OllamaRequestValidationError, a2 as OllamaResponseValidationError, a3 as OllamaServerError, a4 as OllamaServerVersionUnknownError, a5 as OllamaSkillInvalidError, a6 as OllamaSkillNotFoundError, a7 as OllamaStreamError, a8 as OllamaTimeoutError, a9 as OllamaToolTimeoutError, aa as OllamaToolValidationError, ab as OllamaUnsupportedCapabilityError, ac as RequestContext, ad as RequestLifecycleEvent, ae as ResponseContext, af as SseEvent, ag as ThinkingEvent, ah as TokenEvent, ai as ToolCallEvent, aj as composeMiddleware, ak as createConsoleLogger, al as extractUsage, am as mapError, an as parseSseStream } from './runtime-BIjr5ME4.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-CFuv7Ifh.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 OllamaQuotaExceededError, a0 as OllamaRateLimitError, a1 as OllamaRequestTooLargeError, a2 as OllamaRequestValidationError, a3 as OllamaResponseValidationError, a4 as OllamaServerError, a5 as OllamaServerVersionUnknownError, a6 as OllamaSkillInvalidError, a7 as OllamaSkillNotFoundError, a8 as OllamaStreamError, a9 as OllamaTimeoutError, aa as OllamaToolTimeoutError, ab as OllamaToolValidationError, ac as OllamaUnsupportedCapabilityError, ad as RequestContext, ae as RequestLifecycleEvent, af as ResponseContext, ag as SseEvent, ah as ThinkingEvent, ai as TokenEvent, aj as ToolCallEvent, ak as composeMiddleware, al as createConsoleLogger, am as extractUsage, an as isNetworkLevelError, ao as mapError, ap as parseSseStream } from './runtime-CFuv7Ifh.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-DrDUfbfQ.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-DrDUfbfQ.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-CTv2acbj.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-CTv2acbj.js';
 import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-CeFbHJeO.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-CeFbHJeO.js';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.js';
@@ -970,8 +970,8 @@ declare class ModelsClient {
      * model-not-found (404), or VRAM-exhaustion failures.
      */
     pin(model: string): Promise<void>;
-    createBlob(digest: string, data: BinaryBody): Promise<void>;
-    checkBlob(digest: string): Promise<boolean>;
+    createBlob(digest: string, data: BinaryBody, request?: RequestCancellationOptions): Promise<void>;
+    checkBlob(digest: string, request?: RequestCancellationOptions): Promise<boolean>;
     /**
      * Computes a blob digest the way Ollama's content-addressed store expects:
      * SHA-256 over the raw bytes, formatted as `sha256:<64 lowercase hex>`.
@@ -992,17 +992,44 @@ declare class ModelsClient {
      */
     createBlobFromData(data: Uint8Array, opts?: {
         readonly digest?: string | undefined;
-        readonly signal?: AbortSignal | undefined;
-    }): Promise<BlobUploadResult>;
+    } & RequestCancellationOptions): Promise<BlobUploadResult>;
+    /**
+     * Streams a blob upload straight from a web `ReadableStream` — the
+     * multi-gigabyte-safe counterpart of {@link createBlobFromData}. The body
+     * is never materialized in memory: the transport hands the stream to
+     * `fetch` directly (setting `duplex: 'half'`, which Node 18+ requires for
+     * stream bodies), so peak heap usage is a transport-level chunk, not the
+     * blob size.
+     *
+     * The digest must be known up front — it *is* the upload URL
+     * (`/api/blobs/<digest>`), the same content-addressed protocol
+     * `curl -T` performs. Hash first when you don't have it: in-memory bytes
+     * via {@link computeBlobDigest}, files via {@link createBlobFromFile}
+     * (which hashes in a streaming pass). The server verifies the streamed
+     * bytes against the digest and rejects mismatches, so a corrupted or
+     * truncated stream fails the upload instead of poisoning the store.
+     */
+    createBlobFromStream(digest: string, stream: ReadableStream<Uint8Array>, request?: RequestCancellationOptions): Promise<BlobUploadResult>;
     /**
      * 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.
+     *
+     * Streams both passes in fixed-size chunks — peak heap is O(chunk), not
+     * O(file), so multi-gigabyte GGUFs never enter the Node heap:
+     *
+     *  1. **Hash pass** (skipped when `opts.digest` is provided): the file is
+     *     streamed through `node:crypto`'s incremental SHA-256.
+     *  2. **Upload pass**: `node:fs` createReadStream → web ReadableStream →
+     *     `fetch` body with `duplex: 'half'` (see {@link createBlobFromStream}).
+     *
+     * A pre-existing blob (HEAD 200) skips the upload pass entirely, same as
+     * {@link createBlobFromData}.
      */
     createBlobFromFile(path: string, opts?: {
-        readonly signal?: AbortSignal | undefined;
-    }): Promise<BlobUploadResult & {
+        readonly digest?: string | undefined;
+    } & RequestCancellationOptions): Promise<BlobUploadResult & {
         readonly fileName: string;
     }>;
     /**
@@ -2277,8 +2304,8 @@ declare class OllamaClient {
      */
     readonly getContextLength: (request: ContextDiscoveryRequestOptions) => Promise<DiscoveredContextLength>;
     readonly version: () => Promise<VersionResponse>;
-    readonly createBlob: (digest: string, data: BinaryBody) => Promise<void>;
-    readonly checkBlob: (digest: string) => Promise<boolean>;
+    readonly createBlob: (digest: string, data: BinaryBody, request?: RequestCancellationOptions) => Promise<void>;
+    readonly checkBlob: (digest: string, request?: RequestCancellationOptions) => Promise<boolean>;
     /**
      * Immediately unloads `model` from VRAM. Convenience alias for
      * {@link ModelsClient.unload} — see that method for the full
@@ -2780,6 +2807,140 @@ declare function toDataStream<TChunk, TFinal>(stream: OllamaStream<TChunk, TFina
  */
 declare function toResponse<TChunk, TFinal>(stream: OllamaStream<TChunk, TFinal>, init?: ResponseInit): Response;
 
+/**
+ * Zero-copy stream observation — the safe alternative to `ReadableStream.tee()`
+ * for multi-sink consumption (audit logging, token counting, telemetry taps).
+ *
+ * ## The `tee()` hazard this exists for
+ *
+ * Developers streaming to a UI while also feeding a logger (or a token
+ * counter, or an OpenTelemetry exporter) typically reach for:
+ *
+ * ```ts
+ * // VULNERABLE PATTERN — do not do this
+ * const [forUi, forLogger] = response.body.tee();
+ * ```
+ *
+ * WHATWG `tee()` branches share a single upstream pull mechanism: a branch
+ * that reads slower than its sibling forces every intermediate chunk to be
+ * retained in that branch's internal queue until it catches up. If the slow
+ * consumer is a logger waiting on a database write — or never drains at all —
+ * the queue grows without bound, and because both branches apply shared
+ * backpressure, the *fast* consumer is throttled by the slowest one. In a
+ * long-lived streaming server this is a slow, silent heap leak.
+ *
+ * ## What `observeStream` does instead
+ *
+ * A single-pass wrapper: chunks flow from the source through the observer
+ * callbacks to the primary consumer with **no second queue and no forked
+ * stream**. The contract is deliberately one-sided in favor of the primary
+ * consumer:
+ *
+ *   - **Never blocks.** Observer callbacks run on a serialized microtask
+ *     chain, not on the hot path. A slow async observer (a logger waiting on
+ *     I/O) delays only its own tail — the primary consumer keeps receiving
+ *     chunks at source speed.
+ *   - **Never fails.** An observer that throws (sync) or rejects (async) is
+ *     routed to `onListenerError` and otherwise discarded. Observer failures
+ *     can never poison the primary pipeline.
+ *   - **Never leaks via the wrapper.** There is no second branch to
+ *     backpressure. The only retained state is one closure per backlogged
+ *     observer callback; if your observer can stall *forever*, bound it on
+ *     your side (queue, drop policy) — the wrapper will keep enqueueing
+ *     otherwise, exactly like any fire-and-forget log sink.
+ *   - **Ordered.** Observer callbacks run strictly FIFO, one at a time —
+ *     async sinks see chunks in stream order, and `onDone` is enqueued only
+ *     after the last chunk's callback settles. (This is intentionally
+ *     stricter than a naive `void onChunk(chunk)` fire-and-forget, which
+ *     runs concurrent, out-of-order observers and turns a rejected async
+ *     callback into an unhandled rejection.)
+ *
+ * ## Lifecycle
+ *
+ *   - Source completes naturally → `onDone` (enqueued after the last chunk
+ *     callback settles, so a logger has flushed everything it saw).
+ *   - Source throws → `onError(err)` immediately, then the error re-throws to
+ *     the primary consumer (the observer is transparent, not a circuit
+ *     breaker).
+ *   - Primary consumer stops early (`break` / `return` / `throw` inside the
+ *     `for await` loop) → `onAbandon()` immediately. This is distinct from
+ *     completion: the source's iterator-`return()` has already closed the
+ *     underlying transport by the time `onAbandon` fires.
+ *
+ * Works over any `AsyncIterable<T>` — the SDK's `OllamaStream` (streaming
+ * `chat`/`generate`), the raw NDJSON chunk iterables, or your own sources.
+ * Note that `OllamaStream` itself is dual-mode but mode-exclusive (`.on()`
+ * listeners cannot be combined with `for await`); `observeStream` is the
+ * supported way to tap a stream you are already iterating.
+ */
+/**
+ * Lifecycle phase an observer failure came from. `'chunk'` and `'done'`
+ * failures arrive from the serialized callback chain; `'error'` and
+ * `'abandon'` failures come from those terminal hooks themselves.
+ */
+type StreamObserverPhase = 'chunk' | 'done' | 'error' | 'abandoned';
+/** Passive, best-effort observer hooks — see the module docs for semantics. */
+interface StreamObserverCallbacks<T> {
+    /**
+     * Called once per chunk, in stream order, FIFO, never overlapping with a
+     * previous still-running call. May be sync (`void`) or async
+     * (`Promise<void>`); async return values are awaited *on the observer
+     * chain only* — they never delay the primary consumer. Rejections (and
+     * sync throws) route to {@link StreamObserverCallbacks.onListenerError}.
+     */
+    onChunk?: ((chunk: T) => void | Promise<void>) | undefined;
+    /**
+     * Called with the source's error immediately before that error is re-thrown
+     * to the primary consumer. A throwing `onError` hook cannot mask the
+     * original error — it is reported via {@link StreamObserverCallbacks.onListenerError}
+     * and the original error still propagates.
+     */
+    onError?: ((error: unknown) => void) | undefined;
+    /**
+     * Called when the source completes naturally — enqueued after the last
+     * chunk's observer callback settles, so a flushed logger has seen every
+     * chunk before its "done" marker.
+     */
+    onDone?: (() => void | Promise<void>) | undefined;
+    /**
+     * Called when the primary consumer stops early (`break`/`return`/`throw` in
+     * the consuming loop). The source has already been closed via the
+     * iterator-`return()` protocol when this fires. `onDone` does not fire in
+     * this case.
+     */
+    onAbandon?: (() => void) | undefined;
+    /**
+     * The observation failure channel: any observer hook that throws or rejects
+     * is reported here together with the phase it came from, and then
+     * discarded. If this hook itself throws, the failure is swallowed — an
+     * error reporter must never become the next unhandled rejection.
+     */
+    onListenerError?: ((error: unknown, phase: StreamObserverPhase) => void) | undefined;
+}
+/**
+ * Wraps an `AsyncIterable` with passive observer hooks without creating a
+ * secondary buffered stream queue — avoiding the memory retention and shared
+ * backpressure penalties of `ReadableStream.tee()`.
+ *
+ * @example
+ * ```ts
+ * const stream = await client.chat({ model: 'llama4', messages, stream: true });
+ * let tokens = 0;
+ * const observed = observeStream(stream, {
+ *   onChunk: (event) => {
+ *     if (event.type === 'token') tokens += 1;
+ *     auditLog.write(event); // slow async sink — never delays the consumer
+ *   },
+ *   onDone: () => auditLog.flush(),
+ *   onListenerError: (err) => telemetry.count('audit_log_failure', err),
+ * });
+ * for await (const event of observed) {
+ *   ui.render(event); // primary consumer — full speed, full order
+ * }
+ * ```
+ */
+declare function observeStream<T>(source: AsyncIterable<T>, callbacks?: StreamObserverCallbacks<T>): AsyncGenerator<T, void, unknown>;
+
 /**
  * Client-side usage budgeting.
  *
@@ -3695,7 +3856,33 @@ interface ContextCheck {
     readonly windowSource: ContextWindowSource;
     /** True when the estimate crossed the warning threshold of the effective window. */
     readonly exceedsThreshold: boolean;
+    /**
+     * Present only when `exceedsThreshold` is `true`: the smallest power-of-two
+     * window with ~30% generation headroom above the estimate (see
+     * {@link recommendContextWindow}). A starting point, not a verdict — check
+     * the model's native ceiling with `client.models.getContextLength()` before
+     * adopting it; a prompt that outgrows the native maximum needs compaction
+     * or history truncation, not a bigger `num_ctx`.
+     */
+    readonly recommendedNumCtx?: number | undefined;
 }
+/**
+ * Smallest power-of-two context window that comfortably fits
+ * `estimatedTokens` — ~30% headroom for the response, floored at 4096 (the
+ * common modern server default when `num_ctx` is unset).
+ *
+ * Uses an exact doubling loop rather than
+ * `Math.pow(2, Math.ceil(Math.log2(x)))`: floating-point `log2` of exact
+ * powers of two can land marginally above the integer (e.g.
+ * `Math.log2(8) > 3` on some platforms), which rounds a perfect fit *up* a
+ * whole power of two. The loop has no such boundary bugs.
+ *
+ * Non-finite / non-positive inputs return the 4096 floor rather than throwing:
+ * callers use this to *suggest* a window after their own estimate already
+ * flagged a problem, so garbage-in should degrade to a conservative
+ * suggestion, not a second error path.
+ */
+declare function recommendContextWindow(estimatedTokens: number): number;
 interface ContextCheckOptions {
     /** Client `defaultContextLength`, applied when the request doesn't set `num_ctx`. */
     readonly defaultContextLength?: number | undefined;
@@ -3862,4 +4049,4 @@ declare class ModelAffinityScheduler {
 /** Convenience factory — `createModelAffinityScheduler(client, opts)` reads better in setups. */
 declare function createModelAffinityScheduler(client: ModelAffinityClient | OllamaClient, options?: ModelAffinitySchedulerOptions): ModelAffinityScheduler;
 
-export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, AbortableAsyncIterable, type AffinityRunningModel, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, BalanceRequestOptions, type BalanceResponse, type BlobUploadResult, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, type CompactionOptions, type CompareDraftPerformanceOptions, type ContextCheck, type ContextCheckOptions, type ContextDiscoveryRequestOptions, type ContextLengthSignals, type ContextLengthSource, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, type CreateModelFromGgufOptions, CreateRequestOptions, type CumulativeCacheStats, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, type DefineToolOptions, DeleteRequestOptions, type DiscoveredContextLength, type DraftBenchmarkClient, type DraftPerformanceComparison, type DraftRunStats, type EmbedBatchOptions, type EmbedBatchResult, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, type FormattedTelemetry, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, type HistorySanitizeOptions, HttpClient, IMAGE_TOKEN_ESTIMATE, type IncludedBalance, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, type KeepAlive, type KnownDoneReason, type LegacyBalanceLimit, type LegacyIncludedBalance, type LoadMcpToolsOptions, Logger, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelAffinityClient, ModelAffinityRouter, type ModelAffinityRoutingOptions, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, type ModelAffinitySnapshot, type ModelAffinityStats, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, type OversizedEmbedInput, type ParallelToolCallBehavior, PingResult, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, type RawOllamaMetrics, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, type SessionCompactionOptions, type SessionCompactionResult, type SessionTurn, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type SupportedSchema, type SystemOneAnswer, type SystemOneAnswers, SystemOneChoiceAnswer, SystemOneChoiceQuestion, SystemOneContent, SystemOneNoulAnswer, SystemOneNoulQuestion, type SystemOneQuestion, type SystemOneQuestions, type SystemOneRequest, type SystemOneResponse, SystemOneScoreAnswer, SystemOneScoreQuestion, type SystemOneUsage, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolCallAccumulator, ToolDefinition, ToolExecutionResult, ToolHandler, ToolParameters, ToolRegistry, type TurnCacheStats, type UsageBucket, type UsageMetrics, UsageRequestOptions, type UsageResponse, VersionResponse, VisionInput, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchRequestOptions, WebFetchResponse, type WebFetchToolParams, WebSearchRequestOptions, WebSearchResponse, type WebSearchToolParams, type WebToolsClient, type WebToolsOptions, addSpanEvent, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, compareDraftPerformance, contextWarningMessage, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };
+export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, AbortableAsyncIterable, type AffinityRunningModel, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, BalanceRequestOptions, type BalanceResponse, type BlobUploadResult, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, type CompactionOptions, type CompareDraftPerformanceOptions, type ContextCheck, type ContextCheckOptions, type ContextDiscoveryRequestOptions, type ContextLengthSignals, type ContextLengthSource, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, type CreateModelFromGgufOptions, CreateRequestOptions, type CumulativeCacheStats, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, type DefineToolOptions, DeleteRequestOptions, type DiscoveredContextLength, type DraftBenchmarkClient, type DraftPerformanceComparison, type DraftRunStats, type EmbedBatchOptions, type EmbedBatchResult, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, type FormattedTelemetry, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, type HistorySanitizeOptions, HttpClient, IMAGE_TOKEN_ESTIMATE, type IncludedBalance, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, type KeepAlive, type KnownDoneReason, type LegacyBalanceLimit, type LegacyIncludedBalance, type LoadMcpToolsOptions, Logger, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelAffinityClient, ModelAffinityRouter, type ModelAffinityRoutingOptions, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, type ModelAffinitySnapshot, type ModelAffinityStats, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, type OversizedEmbedInput, type ParallelToolCallBehavior, PingResult, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, type RawOllamaMetrics, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, type SessionCompactionOptions, type SessionCompactionResult, type SessionTurn, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type StreamObserverCallbacks, type StreamObserverPhase, type SupportedSchema, type SystemOneAnswer, type SystemOneAnswers, SystemOneChoiceAnswer, SystemOneChoiceQuestion, SystemOneContent, SystemOneNoulAnswer, SystemOneNoulQuestion, type SystemOneQuestion, type SystemOneQuestions, type SystemOneRequest, type SystemOneResponse, SystemOneScoreAnswer, SystemOneScoreQuestion, type SystemOneUsage, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolCallAccumulator, ToolDefinition, ToolExecutionResult, ToolHandler, ToolParameters, ToolRegistry, type TurnCacheStats, type UsageBucket, type UsageMetrics, UsageRequestOptions, type UsageResponse, VersionResponse, VisionInput, WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchRequestOptions, WebFetchResponse, type WebFetchToolParams, WebSearchRequestOptions, WebSearchResponse, type WebSearchToolParams, type WebToolsClient, type WebToolsOptions, addSpanEvent, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, compareDraftPerformance, contextWarningMessage, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, createWebFetchTool, createWebSearchTool, createWebTools, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, formatWebFetchResult, formatWebSearchResult, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, observeStream, parseNdjsonStream, parseStructuredOutput, recommendContextWindow, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };