@nemesis-oss/ollama-sdk 1.7.0 → 1.9.0

package/dist/index.d.cts

@@ -1,14 +1,127 @@
-import { F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, H as HttpClient, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, e as SseEvent, f as OllamaClientError, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, g as RawUsageSource, T as TokenUsage } from './runtime-bQ48I-RC.cjs';
-export { D as DoneEvent, E as ErrorEvent, h as HttpBody, i as HttpClientOptions, j as HttpRequestOptions, k as LifecycleErrorEvent, l as LifecycleRetryEvent, m as LifecycleStartEvent, n as LifecycleSuccessEvent, o as LogFn, p as MessageEvent, q as MiddlewareContext, N as NANOS_PER_MS, r as NANOS_PER_SECOND, s as NOOP_LOGGER, t as NextFunction, u as OllamaAbortError, v as OllamaAgentMaxIterationsError, w as OllamaAgentMaxToolCallsError, x as OllamaAuthError, y as OllamaClientErrorOptions, z as OllamaErrorRequestContext, J as OllamaErrorResponseContext, K as OllamaGenericClientError, Q as OllamaIncompatibleModelError, U as OllamaMcpError, V as OllamaModelRoutingError, W as OllamaNetworkError, X as OllamaNotFoundError, Y as OllamaQuotaExceededError, Z as OllamaRateLimitError, _ as OllamaRequestValidationError, $ as OllamaServerError, a0 as OllamaSkillInvalidError, a1 as OllamaSkillNotFoundError, a2 as OllamaTimeoutError, a3 as OllamaToolTimeoutError, a4 as OllamaToolValidationError, a5 as OllamaUnsupportedCapabilityError, a6 as RequestContext, a7 as RequestLifecycleEvent, a8 as ResponseContext, a9 as ThinkingEvent, aa as TokenEvent, ab as ToolCallEvent, ac as composeMiddleware, ad as createConsoleLogger, ae as extractUsage, af as mapError, ag as parseSseStream } from './runtime-bQ48I-RC.cjs';
-import { T as ThinkingMetadata, M as ModelResponse, 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 ChatRequestOptions, h as ChatResponse, G as GenerateRequestOptions, i as GenerateResponse, E as EmbedRequestOptions, j as EmbedResponse, k as EmbeddingsRequestOptions, l as EmbeddingsResponse, W as WebSearchRequestOptions, m as WebSearchResponse, n as WebFetchRequestOptions, o as WebFetchResponse, p as ToolDefinition, q as ToolCall, r as Message, s as ModelOptions, t as ThinkValue } from './types-5PAjLoCp.cjs';
-export { F as FormatOption, L as ListResponse, u as Logprob, v as LogprobToken, w as ModelDetails, R as RequestCancellationOptions, x as Role, y as ToolCallFunction, z as ToolFunctionDefinition, A as ToolParameters, B as ToolProperty, H as WebSearchResult } from './types-5PAjLoCp.cjs';
+import { F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, H as HttpClient, 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-D2W9TfCJ.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 OllamaAuthError, w as OllamaBadGatewayError, x as OllamaClientError, y as OllamaClientErrorOptions, z as OllamaErrorRequestContext, J as OllamaErrorResponseContext, K as OllamaGenericClientError, Q as OllamaIncompatibleModelError, U as OllamaMcpError, V as OllamaModelRoutingError, W as OllamaNetworkError, X as OllamaNotFoundError, Y as OllamaOverloadedError, Z as OllamaQuotaExceededError, _ as OllamaRateLimitError, $ as OllamaRequestTooLargeError, a0 as OllamaRequestValidationError, a1 as OllamaResponseValidationError, a2 as OllamaServerError, a3 as OllamaServerVersionUnknownError, a4 as OllamaSkillInvalidError, a5 as OllamaSkillNotFoundError, a6 as OllamaStreamError, a7 as OllamaTimeoutError, a8 as OllamaToolTimeoutError, a9 as OllamaToolValidationError, aa as OllamaUnsupportedCapabilityError, ab as RequestContext, ac as RequestLifecycleEvent, ad as ResponseContext, ae as SseEvent, af as ThinkingEvent, ag as TokenEvent, ah as ToolCallEvent, ai as composeMiddleware, aj as createConsoleLogger, ak as extractUsage, al as mapError, am as parseSseStream } from './runtime-D2W9TfCJ.cjs';
+import { T as ThinkingMetadata, M as ModelResponse, 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, R as RequestCancellationOptions, 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 VisionInput } from './types-DVcX_zMp.cjs';
+export { L as ListResponse, w as Logprob, x as LogprobToken, y as ModelDetails, z as Role, A as ToolCallFunction, H as ToolFunctionDefinition, I as ToolProperty, J as UsageRange, K as UsageScope, N as WebSearchResult, O as imageStringNeedsResolution, Q as resolveImageInput } from './types-DVcX_zMp.cjs';
 import { z } from 'zod';
-import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-DS-UWFx8.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-DS-UWFx8.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-BIh45UXj.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 OllamaOpenAICompletionRequest, a4 as OllamaOpenAIEmbeddingRequest, a5 as OllamaOpenAIReasoningEffort, a6 as OllamaOpenAIResponsesRequest, a7 as OpenAIChatCompletionChoice, b as OpenAIChatCompletionChunk, a8 as OpenAIChatCompletionChunkChoice, a9 as OpenAIChatCompletionDelta, O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, aa as OpenAIChatCompletionStream, ab as OpenAICompletionChoice, e as OpenAICompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, ac as OpenAICompletionStream, ad as OpenAIContentPart, ae as OpenAIEmbeddingInput, af as OpenAIEmbeddingItem, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, ag as OpenAIFunctionDefinition, ah as OpenAIImageUrlContentPart, h as OpenAIListModelsResponse, ai as OpenAIMessage, i as OpenAIModelItem, aj as OpenAIReasoningEffort, ak as OpenAIResponseFormat, al as OpenAIResponsesCompletedEvent, am as OpenAIResponsesContentPartAddedEvent, an as OpenAIResponsesContentPartDoneEvent, ao as OpenAIResponsesCreatedEvent, ap as OpenAIResponsesError, aq as OpenAIResponsesEventBase, ar as OpenAIResponsesFailedEvent, as as OpenAIResponsesFunctionCallArgumentsDeltaEvent, at as OpenAIResponsesFunctionCallArgumentsDoneEvent, au as OpenAIResponsesInProgressEvent, av as OpenAIResponsesIncompleteDetails, aw as OpenAIResponsesIncompleteEvent, ax as OpenAIResponsesOutputContent, ay as OpenAIResponsesOutputFunctionCall, az as OpenAIResponsesOutputItem, aA as OpenAIResponsesOutputItemAddedEvent, aB as OpenAIResponsesOutputItemDoneEvent, aC as OpenAIResponsesOutputMessage, aD as OpenAIResponsesOutputReasoning, aE as OpenAIResponsesOutputRefusal, aF as OpenAIResponsesOutputTextContent, aG as OpenAIResponsesOutputTextDeltaEvent, aH as OpenAIResponsesOutputTextDoneEvent, aI as OpenAIResponsesQueuedEvent, aJ as OpenAIResponsesReasoningSummaryPartAddedEvent, aK as OpenAIResponsesReasoningSummaryPartDoneEvent, aL as OpenAIResponsesReasoningSummaryTextDeltaEvent, aM as OpenAIResponsesReasoningSummaryTextDoneEvent, aN as OpenAIResponsesReasoningTextDeltaEvent, aO as OpenAIResponsesReasoningTextDoneEvent, aP as OpenAIResponsesRefusalDeltaEvent, aQ as OpenAIResponsesRefusalDoneEvent, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, aR as OpenAIResponsesStatus, aS as OpenAIResponsesStream, aT as OpenAIResponsesStreamError, l as OpenAIResponsesStreamEvent, aU as OpenAIResponsesUsage, aV as OpenAIStreamOptions, aW as OpenAITextContentPart, aX as OpenAITool, aY as OpenAIToolCall, aZ as OpenAIToolCallDelta, a_ as OpenAIUsage, a$ as SystemOneConfidence, b0 as SystemOneProbabilities } from './anthropic-BIh45UXj.cjs';
+import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-Dj6FdF2n.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-Dj6FdF2n.cjs';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.cjs';
 export { d as McpContentBlock, e as McpCreateTaskResult, f as McpElicitationFormRequest, g as McpElicitationHandlers, h as McpElicitationRequest, i as McpElicitationResult, j as McpElicitationUrlRequest, k as McpIcon, l as McpInputRequiredResult, m as McpListToolsParams, n as McpListToolsResult, o as McpRequestOptions, p as McpServerCapabilities, q as McpTaskMethod, r as McpTaskRequest, s as McpTaskStatus, t as McpToolAnnotations, u as McpToolCallResult, v as McpToolExecution } from './types-CI-gM2u5.cjs';
 import * as Otel from '@opentelemetry/api';
 
+/**
+ * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
+ * Source: contracts/ir/ollama.ir.json (canonical Ollama IR).
+ * See ADR 0013 and ADR 0014 for the contract-first architecture.
+ */
+
+interface BalanceResponse {
+    readonly included: IncludedBalance | LegacyIncludedBalance;
+    readonly purchased: {
+        /** Remaining unexpired purchased credits in USD. */
+        readonly balance_usd: number;
+    };
+}
+
+/**
+ * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
+ * Source: contracts/ir/ollama.ir.json (canonical Ollama IR).
+ * See ADR 0013 and ADR 0014 for the contract-first architecture.
+ */
+interface IncludedBalance {
+    /** Remaining included credits in USD. */
+    readonly balance_usd: number;
+    /** Included credits available for the full period in USD. */
+    readonly allowance_usd: number;
+    readonly period: {
+        /** Start of the included period in UTC, inclusive. */
+        readonly from: string;
+        /** End of the included period in UTC, exclusive. */
+        readonly until: string;
+    };
+}
+
+/**
+ * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
+ * Source: contracts/ir/ollama.ir.json (canonical Ollama IR).
+ * See ADR 0013 and ADR 0014 for the contract-first architecture.
+ */
+interface LegacyBalanceLimit {
+    /** Percentage of the limit remaining. */
+    readonly remaining_percent: number;
+    /** Next reset time in UTC. */
+    readonly resets_at: string;
+}
+
+/**
+ * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
+ * Source: contracts/ir/ollama.ir.json (canonical Ollama IR).
+ * See ADR 0013 and ADR 0014 for the contract-first architecture.
+ */
+
+interface LegacyIncludedBalance {
+    readonly session: LegacyBalanceLimit;
+    readonly weekly: LegacyBalanceLimit;
+}
+
+/**
+ * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
+ * Source: contracts/ir/ollama.ir.json (canonical Ollama IR).
+ * See ADR 0013 and ADR 0014 for the contract-first architecture.
+ */
+
+type UsageBucket = UsageMetrics & {
+    /** Start of the bucket in UTC, inclusive. */
+    readonly from: string;
+    /** End of the bucket in UTC, exclusive. */
+    readonly until: string;
+    /** Present and true for the current hour or day, which is still in progress. */
+    readonly partial?: boolean | undefined;
+};
+
+/**
+ * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
+ * Source: contracts/ir/ollama.ir.json (canonical Ollama IR).
+ * See ADR 0013 and ADR 0014 for the contract-first architecture.
+ */
+interface UsageMetrics {
+    /** Number of recorded requests. */
+    readonly request_count: number;
+    /** Total value of the requests in USD, including usage covered by your plan and usage paid from purchased credits. */
+    readonly usage_usd?: number | undefined;
+    /** Recorded input tokens, including cached input tokens. */
+    readonly input_tokens?: number | undefined;
+    /** Recorded input tokens read from cache, already included in input_tokens. */
+    readonly cached_input_tokens?: number | undefined;
+    /** Recorded output tokens. */
+    readonly output_tokens?: number | undefined;
+}
+
+/**
+ * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
+ * Source: contracts/ir/ollama.ir.json (canonical Ollama IR).
+ * See ADR 0013 and ADR 0014 for the contract-first architecture.
+ */
+
+interface UsageResponse {
+    /** Selected time range. */
+    readonly range: '24h' | '7d' | '30d';
+    /** Selected usage scope. */
+    readonly scope: 'self' | 'team';
+    /** Set automatically - hour for 24h, day for 7d and 30d. */
+    readonly granularity: 'hour' | 'day';
+    /** Start of the range in UTC, inclusive. */
+    readonly from: string;
+    /** End of the range in UTC, exclusive. */
+    readonly until: string;
+    /** Usage across the entire range. */
+    readonly totals: UsageMetrics;
+    /** Usage in chronological order, including buckets with no recorded requests. */
+    readonly buckets: readonly UsageBucket[];
+}
+
 /**
  * Exponential backoff with full jitter calculation.
  */
@@ -289,6 +402,31 @@ interface OllamaClientConfig {
     readonly logger?: Logger;
     /** Enables console debug logger if true. */
     readonly debug?: boolean;
+    /**
+     * 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`.
+     */
+    readonly defaultContextLength?: number;
+    /**
+     * Fraction of the effective context window at which the client warns that
+     * a request's estimated prompt size is approaching truncation (default
+     * `0.9` — see `DEFAULT_CONTEXT_WARNING_THRESHOLD`).
+     */
+    readonly contextWarningThreshold?: number;
+    /**
+     * What happens when the pre-flight context check (see
+     * `src/context-safety.ts`) concludes a request will likely be truncated:
+     * `'warn'` (default) logs a warning through the configured logger and sends
+     * the request anyway; `'throw'` rejects the request client-side with
+     * `OllamaClientError` before anything hits the wire. `'throw'` is the
+     * safety-critical choice — use it when silent history truncation would
+     * corrupt application behavior (e.g. long-context RAG, agents).
+     */
+    readonly onContextOverflow?: 'warn' | 'throw';
     /** Request lifecycle hook for telemetry/metrics. */
     readonly onLifecycleEvent?: RequestLifecycleHook;
 }
@@ -312,6 +450,20 @@ declare function checkEndpointHealth(endpoint: OllamaEndpoint, fetchImpl?: Fetch
  */
 
 type RuntimeMode = 'local' | 'cloud' | 'unknown';
+/**
+ * Best-effort classification of a model's parallel tool-call emission
+ * behavior. Used by agent loops that need to know whether the model
+ * is likely to emit multiple `tool_calls` in a single assistant
+ * message (parallel) or one-at-a-time (sequential).
+ *
+ * This is a **heuristic** derived from runtime mode + model family
+ * pattern matching against `/api/show`'s reported model_info. The
+ * SDK does NOT normalize between cloud and local — it reports the
+ * best assessment it can and lets the caller decide how to act.
+ *
+ * See ADR 0023 for the rationale and the recommended caller pattern.
+ */
+type ParallelToolCallBehavior = 'yes' | 'no' | 'unknown';
 interface ModelCapabilities {
     readonly model: string;
     readonly reported: readonly string[];
@@ -336,6 +488,44 @@ interface ModelCapabilities {
      * making a network call that Ollama Cloud is known to reject.
      */
     readonly supportsStructuredOutputRequest: boolean;
+    /**
+     * Best-effort inference of whether the model is likely to emit
+     * **multiple `tool_calls` in a single assistant message** (parallel)
+     * vs **one tool call per assistant turn** (sequential).
+     *
+     * The SDK does NOT normalize between cloud and local — it reports
+     * the best assessment it can and lets the caller decide. Agent
+     * authors who need hard sequential execution should set
+     * `ToolRegistry`'s `maxConcurrency: 1` regardless of this field's
+     * value, since the model's behavior is not deterministic across
+     * prompts.
+     *
+     * Inference matrix (see ADR 0023):
+     *
+     *   - **`'yes'`** — the model is known to emit parallel tool calls:
+     *     - Cloud-mode endpoints (the OpenAI/Anthropic compat bridges
+     *       proxy to proprietary models like GPT-4o, Claude, which
+     *       freely emit parallel tool calls).
+     *     - Local models from families that ship with parallel-tool-call
+     *       training (Qwen 2.5+, Llama 3.1+ tool-use variants, Mistral
+     *       function-calling fine-tunes, Hermes 2/3, Command R+).
+     *
+     *   - **`'no'`** — the model is known to emit at most one tool call
+     *     per assistant turn. Currently no model family is classified
+     *     as `'no'` by default; the field is reserved for future
+     *     narrowing as more is learned about specific models.
+     *
+     *   - **`'unknown'`** — the model family is not in the known-yes or
+     *     known-no list, OR `/api/show` didn't return enough
+     *     information to make an assessment. Callers should treat
+     *     `'unknown'` as "ask the model and see what it does" — the
+     *     `ToolRegistry` will execute whatever calls the model emits,
+     *     in parallel via `Promise.all` by default.
+     *
+     * See: `src/tools/registry.ts` for `maxConcurrency` enforcement,
+     * and ADR 0023 for the full design rationale.
+     */
+    readonly parallelToolCalls: ParallelToolCallBehavior;
 }
 declare function inferRuntimeMode(baseUrl: string): RuntimeMode;
 declare function detectModelCapabilities(http: HttpClient, model: string, signal?: AbortSignal): Promise<ModelCapabilities>;
@@ -369,23 +559,17 @@ declare class OllamaStream<TChunk, TFinal> implements AsyncIterable<OllamaStream
     [Symbol.asyncIterator](): AsyncGenerator<OllamaStreamEvent<TChunk, TFinal>, void, undefined>;
 }
 
-/**
- * Shared request-runner contract used by native and compatibility clients.
- */
-
-type RequestRunner = <T>(op: (http: HttpClient, signal: AbortSignal) => Promise<T>, opts?: {
-    readonly signal?: AbortSignal | undefined;
-    readonly timeoutMs?: number | undefined;
-    readonly singleEndpoint?: boolean | undefined;
-    readonly model?: string | undefined;
-    /** Defers endpoint capacity release until the returned promise settles. */
-    readonly holdUntil?: ((result: T) => Promise<unknown>) | undefined;
-}) => Promise<T>;
-
 /**
  * Model and blob management operations.
  */
 
+/** Result of a convenience blob upload ({@link ModelsClient.createBlobFromData}). */
+interface BlobUploadResult {
+    /** Content digest (`sha256:<hex>`) of the uploaded payload. */
+    readonly digest: string;
+    /** True when the server already had this blob (HTTP 200) and skipped writing. */
+    readonly alreadyExisted: boolean;
+}
 /**
  * Every operation here targets one specific Ollama server's local model catalog or blob
  * store — unlike `chat`/`generate`/`embed`, a different endpoint isn't an interchangeable
@@ -424,881 +608,764 @@ declare class ModelsClient {
     copy(request: CopyRequestOptions): Promise<StatusResponse>;
     ps(): Promise<PsResponse>;
     version(): Promise<VersionResponse>;
+    /**
+     * Immediately unloads `model` from VRAM/RAM by issuing an empty
+     * `/api/generate` request with `keep_alive: 0`. The server
+     * finalizes any in-flight generation, releases the model's
+     * weights from GPU memory, and frees the slot for subsequent
+     * pipelines (e.g. swap a vision encoder out before loading an
+     * LLM).
+     *
+     * This is the ergonomic equivalent of:
+     *
+     * ```ts
+     * client.generate({ model, prompt: '', keep_alive: 0 });
+     * ```
+     *
+     * Use {@link pin} for the opposite lifecycle — pinning a model
+     * indefinitely in VRAM for hot-loop inference.
+     *
+     * Resolves once the server acknowledges the unload. The promise
+     * rejects on transport errors, model-not-found (404), or auth
+     * failures — callers handling transient issues can retry via the
+     * standard {@link withRetry} policy.
+     *
+     * See: https://github.com/ollama/ollama/blob/main/docs/faq.md
+     *      #how-do-i-keep-a-model-loaded-in-memory-or-make-it-unload-immediately
+     */
+    unload(model: string): Promise<void>;
+    /**
+     * Pre-loads and pins `model` into VRAM indefinitely by issuing an
+     * empty `/api/generate` request with `keep_alive: -1`. The server
+     * loads the model into GPU memory (paying the cold-load latency
+     * once) and keeps it resident until either:
+     *
+     *   - an explicit {@link unload} call is made,
+     *   - the server process is restarted, or
+     *   - the host runs out of VRAM and the server's own eviction
+     *     policy kicks in.
+     *
+     * This is the ergonomic equivalent of:
+     *
+     * ```ts
+     * client.generate({ model, prompt: '', keep_alive: -1 });
+     * ```
+     *
+     * Use {@link unload} to release the pinned slot when the hot loop
+     * is done — leaving models pinned indefinitely exhausts VRAM and
+     * starves subsequent pipelines.
+     *
+     * Resolves once the server acknowledges the pin (i.e. the model
+     * is fully loaded). The promise rejects on transport errors,
+     * model-not-found (404), or VRAM-exhaustion failures.
+     */
+    pin(model: string): Promise<void>;
     createBlob(digest: string, data: BinaryBody): Promise<void>;
     checkBlob(digest: string): 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>`.
+     *
+     * Uses the Web Crypto API (`crypto.subtle.digest`), which exists in every
+     * supported runtime — Node.js ≥ 19 exposes it as a global (this SDK
+     * requires Node ≥ 20), and browsers/edge runtimes have always had it.
+     */
+    computeBlobDigest(data: Uint8Array): Promise<string>;
+    /**
+     * Computes the SHA-256 digest of `data` and pushes it as a blob in one
+     * step — the content-addressed upload Ollama's own tooling performs
+     * (`curl -T file http://…/api/blobs/sha256:…`). Returns the digest, which
+     * `/api/create`'s `files` field references.
+     *
+     * Pass `digest` to skip recomputation when the caller already knows it —
+     * the server verifies the content against the digest and rejects mismatches.
+     */
+    createBlobFromData(data: Uint8Array, opts?: {
+        readonly digest?: string | undefined;
+        readonly signal?: AbortSignal | undefined;
+    }): 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.
+     */
+    createBlobFromFile(path: string, opts?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<BlobUploadResult & {
+        readonly fileName: string;
+    }>;
+    /**
+     * One-shot custom-model publishing from raw GGUF weights, following the
+     * protocol Ollama's API reference documents: push a blob for the GGUF
+     * bytes, then `POST /api/create` with `files: { <fileName>: <digest> }`.
+     * Split GGUFs are supported via `files` — pass every shard's path.
+     *
+     * ```ts
+     * await client.models.createModelFromGguf('my-model', '/path/to/model.gguf', {
+     *   template: '{{ .Prompt }}',
+     * });
+     * ```
+     *
+     * @param model Name for the new model (e.g. `'my-model:latest'`).
+     * @param gguf Path(s) to GGUF file(s) on the local filesystem.
+     * @param opts Everything else `/api/create` accepts (`template`, `system`,
+     *   `parameters`, `license`, `quantize`, …) except `files` and `from`.
+     */
+    createModelFromGguf(model: string, gguf: string | readonly string[], opts?: Omit<CreateRequestOptions, 'model' | 'files' | 'from' | 'stream'>): Promise<ProgressResponse>;
 }
 
 /**
- * OpenAI Compatibility interfaces and client helpers for Ollama.
- * Ollama exposes OpenAI-compatible /v1 endpoints.
+ * Ergonomic OpenAI Responses API bridge — `client.responses.create()`.
  *
- * @remarks
- * This is a typed pass-through to Ollama's own OpenAI-compatible `/v1` endpoints — it
- * implements the subset of the OpenAI API surface that Ollama documents as supported
- * (https://docs.ollama.com/api/openai-compatibility), not the full OpenAI surface (hosted
- * tools like web/file search, computer use, code interpreter, or stateful server-side
- * conversation state). Notably, `tools` is supported by Ollama's compat layer but
- * `tool_choice` and `parallel_tool_calls` are not — both are still typed on
- * {@link OpenAIChatCompletionRequest} (accepted-but-ignored) so consumers passing a
- * standard OpenAI request object don't get spurious type errors; see the `@remarks` on
- * each field. `/v1/responses` is supported non-statefully — see
- * {@link OpenAIResponsesRequest}.
+ * Ollama (v0.13.3+) exposes OpenAI's Responses API at `POST /v1/responses` as
+ * a **stateless** compatibility endpoint: it accepts `model`, `input`,
+ * `instructions`, `tools`, `stream`, `temperature`, `top_p`,
+ * `max_output_tokens`, `reasoning.effort`, `truncation`, and the Ollama
+ * extension `think` — and rejects OpenAI's stateful `previous_response_id` /
+ * `conversation` fields, because every call is independent. Responses deliver
+ * text inside `output[] → message → content[] → output_text` blocks rather
+ * than chat-completion `choices`.
+ *
+ * This module wraps that endpoint with a small, OpenAI-SDK-shaped surface for
+ * teams migrating from `openai.responses.create()` — and adds a safety net the
+ * raw compat layer doesn't have: **dual-mode transport**.
+ *
+ *   1. **Native** — POST `/v1/responses` directly. Used when the server
+ *      supports it (Ollama ≥ v0.13.3, or Ollama Cloud).
+ *   2. **Chat adapter** — on `404 Not Found` (older Ollama builds without the
+ *      endpoint), the same request is transparently re-issued against
+ *      `/api/chat` with `instructions` mapped to a system message,
+ *      `max_output_tokens` to `options.num_predict`, and tools mapped to the
+ *      native tool-definition shape. The response is normalized back into the
+ *      Responses form (`output_text`, `usage.input_tokens`/`output_tokens`),
+ *      so migrating code works unchanged against old servers.
+ *
+ * The `transport` field on the result records which path served the request.
+ *
+ * For the full OpenAI-shaped surface (stateful fields accepted-but-ignored,
+ * raw `output` items, SSE event objects), use `client.openai.responses()`
+ * instead — this module is the ergonomic subset.
  */
 
-interface OpenAIToolCall {
-    readonly id: string;
-    readonly type: 'function';
-    readonly function: {
-        readonly name: string;
-        /** JSON-encoded arguments string, matching OpenAI's wire format (not a parsed object). */
-        readonly arguments: string;
-    };
-}
-interface OpenAITextContentPart {
-    readonly type: 'text';
-    readonly text: string;
-}
-interface OpenAIImageUrlContentPart {
-    readonly type: 'image_url';
-    /** Ollama accepts a data/image URL string or the standard OpenAI URL object. */
-    readonly image_url: string | {
-        readonly url: string;
-        readonly detail?: 'auto' | 'low' | 'high' | 'original' | undefined;
-    };
-}
-type OpenAIContentPart = OpenAITextContentPart | OpenAIImageUrlContentPart;
-interface OpenAIMessage {
-    readonly role: 'system' | 'user' | 'assistant' | 'tool';
-    readonly content: string | readonly OpenAIContentPart[];
-    readonly name?: string | undefined;
-    readonly tool_calls?: readonly OpenAIToolCall[] | undefined;
-    /** Ollama may emit model reasoning alongside assistant content. */
-    readonly reasoning?: string | undefined;
-    /** Set on a `role: 'tool'` message to identify which call this is a result for. */
-    readonly tool_call_id?: string | undefined;
-}
-interface OpenAIStreamOptions {
-    /** Emit a final SSE chunk carrying `usage` (prompt/completion/total tokens) before `[DONE]`. */
-    readonly include_usage?: boolean | undefined;
-}
-interface OpenAIFunctionDefinition {
+/** Flat tool definition, matching the `openai` npm SDK's `tools[]` shape. */
+interface ResponsesToolDefinition {
     readonly name: string;
     readonly description?: string | undefined;
-    readonly parameters?: Record<string, unknown> | undefined;
-}
-interface OpenAITool {
-    readonly type: 'function';
-    readonly function: OpenAIFunctionDefinition;
-}
-type OpenAIReasoningEffort = 'high' | 'medium' | 'low' | 'max' | 'none' | 'minimal' | 'xhigh' | 'ultra' | (string & {});
-type OpenAIResponseFormat = {
-    readonly type: 'text';
-} | {
-    readonly type: 'json_object';
-} | {
-    readonly type: 'json_schema';
-    readonly json_schema: Record<string, unknown>;
-};
-interface OpenAIChatCompletionRequest {
-    readonly model: string;
-    readonly messages: readonly OpenAIMessage[];
-    readonly temperature?: number | undefined;
-    readonly top_p?: number | undefined;
-    readonly stream?: boolean | undefined;
-    /** Only meaningful when `stream: true`; ignored otherwise. */
-    readonly stream_options?: OpenAIStreamOptions | undefined;
-    readonly max_tokens?: number | undefined;
-    readonly stop?: readonly string[] | undefined;
-    readonly response_format?: OpenAIResponseFormat | undefined;
-    readonly seed?: number | undefined;
-    readonly presence_penalty?: number | undefined;
-    readonly frequency_penalty?: number | undefined;
-    readonly user?: string | undefined;
-    readonly logit_bias?: Record<string, number> | undefined;
-    readonly n?: number | undefined;
-    /** Ollama exposes log probabilities for supported reasoning/chat models. */
-    readonly logprobs?: boolean | undefined;
-    readonly top_logprobs?: number | undefined;
-    readonly tools?: readonly OpenAITool[] | undefined;
-    /**
-     * @remarks Accepted for OpenAI compatibility but ignored by Ollama — every tool the
-     * model is given remains callable regardless of this value.
-     */
-    readonly tool_choice?: 'none' | 'auto' | 'required' | {
-        readonly type: 'function';
-        readonly function: {
-            readonly name: string;
-        };
-    } | undefined;
-    /**
-     * @remarks Accepted for OpenAI compatibility but ignored by Ollama — Ollama does not
-     * control tool-call parallelism through this flag.
-     */
-    readonly parallel_tool_calls?: boolean | undefined;
-    /**
-     * Effort level for thinking models (e.g. `deepseek-r1`, `qwen3`). Equivalent to
-     * `reasoning.effort`; only effective for models that support reasoning/thinking.
-     */
-    readonly reasoning_effort?: OpenAIReasoningEffort | undefined;
-    /**
-     * Effort level for thinking models (e.g. `deepseek-r1`, `qwen3`), nested OpenAI-style.
-     * Equivalent to `reasoning_effort`; only effective for models that support
-     * reasoning/thinking.
-     */
-    readonly reasoning?: {
-        readonly effort?: OpenAIReasoningEffort | undefined;
-    } | undefined;
-}
-/** Ollama Chat Completions supports text plus base64 image content via a string image URL. */
-type OllamaOpenAIChatContentPart = OpenAITextContentPart | {
-    readonly type: 'image_url';
-    /** Ollama's current compatibility docs accept an image URL string, including data URLs. */
-    readonly image_url: string;
-};
-type OllamaOpenAIReasoningEffort = 'high' | 'medium' | 'low' | 'max' | 'none';
-type OllamaOpenAIChatMessage = Omit<OpenAIMessage, 'content'> & {
-    readonly content: string | readonly OllamaOpenAIChatContentPart[];
-};
-/** Strict Ollama-documented Chat Completions request; excludes only the SDK-only parallel tool flag. */
-type OllamaOpenAIChatCompletionRequest = Omit<OpenAIChatCompletionRequest, 'messages' | 'parallel_tool_calls' | 'reasoning_effort' | 'reasoning'> & {
-    readonly messages: readonly OllamaOpenAIChatMessage[];
-    readonly reasoning_effort?: OllamaOpenAIReasoningEffort | undefined;
-    readonly reasoning?: {
-        readonly effort?: OllamaOpenAIReasoningEffort | undefined;
-    } | undefined;
-};
-interface OpenAIChatCompletionChoice {
-    readonly index: number;
-    readonly message: OpenAIMessage;
-    readonly finish_reason: string;
-    readonly logprobs?: Record<string, unknown> | null | undefined;
-}
-interface OpenAIToolCallDelta {
-    readonly index: number;
-    readonly id?: string | undefined;
-    readonly type?: 'function' | undefined;
-    readonly function?: {
-        readonly name?: string | undefined;
-        readonly arguments?: string | undefined;
-    } | undefined;
-}
-interface OpenAIChatCompletionDelta {
-    readonly role?: OpenAIMessage['role'] | undefined;
-    readonly content?: string | null | undefined;
-    readonly reasoning?: string | null | undefined;
-    readonly refusal?: string | null | undefined;
-    readonly tool_calls?: readonly OpenAIToolCallDelta[] | undefined;
-}
-interface OpenAIChatCompletionChunkChoice {
-    readonly index: number;
-    readonly delta: OpenAIChatCompletionDelta;
-    readonly finish_reason?: string | null | undefined;
-    readonly logprobs?: Record<string, unknown> | null | undefined;
-}
-interface OpenAIChatCompletionChunk {
-    readonly id: string;
-    readonly object: 'chat.completion.chunk';
-    readonly created: number;
-    readonly model: string;
-    readonly system_fingerprint?: string | undefined;
-    readonly choices: readonly OpenAIChatCompletionChunkChoice[];
-    readonly usage?: {
-        readonly prompt_tokens: number;
-        readonly completion_tokens: number;
-        readonly total_tokens: number;
-    } | null | undefined;
-}
-interface OpenAIUsage {
-    readonly prompt_tokens: number;
-    readonly completion_tokens: number;
-    readonly total_tokens: number;
-    readonly prompt_tokens_details?: {
-        readonly cached_tokens?: number | undefined;
-    } | undefined;
-}
-interface OpenAIChatCompletionResponse {
-    readonly id: string;
-    readonly object: 'chat.completion';
-    readonly created: number;
-    readonly model: string;
-    readonly system_fingerprint?: string | undefined;
-    readonly choices: readonly OpenAIChatCompletionChoice[];
-    readonly usage?: OpenAIUsage | undefined;
-}
-interface OpenAIModelItem {
-    readonly id: string;
-    readonly object: 'model';
-    readonly created: number;
-    readonly owned_by: string;
-}
-interface OpenAIListModelsResponse {
-    readonly object: 'list';
-    readonly data: readonly OpenAIModelItem[];
-}
-interface OpenAICompletionRequest {
-    readonly model: string;
-    /** Ollama currently accepts a string prompt for /v1/completions. */
-    readonly prompt: string;
-    /** Number of log probability alternatives requested for completion tokens. */
-    readonly logprobs?: number | undefined;
-    readonly frequency_penalty?: number | undefined;
-    readonly presence_penalty?: number | undefined;
-    readonly seed?: number | undefined;
-    readonly stop?: readonly string[] | undefined;
-    readonly stream?: boolean | undefined;
-    readonly stream_options?: OpenAIStreamOptions | undefined;
-    readonly temperature?: number | undefined;
-    readonly top_p?: number | undefined;
-    readonly max_tokens?: number | undefined;
-    readonly suffix?: string | undefined;
-    readonly best_of?: number | undefined;
-    readonly echo?: boolean | undefined;
-    readonly logit_bias?: Record<string, number> | undefined;
-    readonly user?: string | undefined;
-    readonly n?: number | undefined;
-}
-/** Strict Ollama-documented Completions request. */
-type OllamaOpenAICompletionRequest = OpenAICompletionRequest;
-interface OpenAICompletionChoice {
-    readonly text: string;
-    readonly index: number;
-    readonly logprobs?: Record<string, unknown> | null | undefined;
-    readonly finish_reason: string | null;
-}
-interface OpenAICompletionChunk {
-    readonly id: string;
-    readonly object: 'text_completion';
-    readonly created: number;
-    readonly model: string;
-    readonly system_fingerprint?: string | undefined;
-    readonly choices: readonly {
-        readonly text: string;
-        readonly index: number;
-        readonly logprobs?: Record<string, unknown> | null | undefined;
-        readonly finish_reason?: string | null | undefined;
-    }[];
-    readonly usage?: {
-        readonly prompt_tokens: number;
-        readonly completion_tokens: number;
-        readonly total_tokens: number;
-    } | null | undefined;
-}
-interface OpenAICompletionResponse {
-    readonly id: string;
-    readonly object: 'text_completion';
-    readonly created: number;
-    readonly model: string;
-    readonly system_fingerprint?: string | undefined;
-    readonly choices: readonly OpenAICompletionChoice[];
-    readonly usage?: OpenAIUsage | undefined;
-}
-type OpenAIEmbeddingInput = string | readonly string[] | readonly number[] | readonly (readonly number[])[];
-interface OpenAIEmbeddingRequest {
-    readonly model: string;
-    readonly input: OpenAIEmbeddingInput;
-    readonly encoding_format?: 'float' | 'base64' | undefined;
-    readonly dimensions?: number | undefined;
-    readonly user?: string | undefined;
-}
-/** Strict Ollama-documented Embeddings request. */
-type OllamaOpenAIEmbeddingRequest = OpenAIEmbeddingRequest;
-interface OpenAIEmbeddingItem {
-    readonly object: 'embedding';
-    readonly embedding: readonly number[] | string;
-    readonly index: number;
-}
-interface OpenAIEmbeddingResponse {
-    readonly object: 'list';
-    readonly data: readonly OpenAIEmbeddingItem[];
-    readonly model: string;
-    readonly usage?: {
-        readonly prompt_tokens: number;
-        readonly total_tokens: number;
-    } | undefined;
+    readonly parameters?: ToolParameters | undefined;
 }
+/** Reasoning effort levels Ollama's `/v1/responses` accepts under `reasoning.effort`. */
+type ResponsesReasoningEffort = 'low' | 'medium' | 'high';
 /**
- * Request body for OpenAI's Responses API (`/v1/responses`), added in Ollama v0.13.3.
- *
- * @remarks
- * Ollama implements this **non-statefully**: every call is independent, so
- * {@link previous_response_id} and {@link conversation} — OpenAI's mechanisms for
- * resuming server-side conversation state — are accepted for compatibility but ignored.
- * Send the full conversation in `input` on every call, the same as `/api/chat`.
+ * Ergonomic request for {@link ResponsesModule.create} — the subset of
+ * OpenAI's Responses API that Ollama supports, minus the stateful fields
+ * (`previous_response_id`, `conversation`) Ollama rejects.
  */
-interface OpenAIResponsesRequest {
+interface ResponsesCreateRequest extends RequestCancellationOptions {
     readonly model: string;
-    readonly input: string | readonly OpenAIMessage[];
+    /** The user prompt. Send the full conversation here — Ollama is stateless. */
+    readonly input: string;
+    /** System/developer instructions, mapped to a system message. */
     readonly instructions?: string | undefined;
-    readonly tools?: readonly OpenAITool[] | undefined;
-    readonly stream?: boolean | undefined;
+    readonly tools?: readonly ResponsesToolDefinition[] | undefined;
     readonly temperature?: number | undefined;
     readonly top_p?: number | undefined;
     readonly max_output_tokens?: number | undefined;
-    /** @remarks Not supported by Ollama, which is stateless across calls — accepted but ignored. */
-    readonly previous_response_id?: string | undefined;
-    /** @remarks Not supported by Ollama, which is stateless across calls — accepted but ignored. */
-    readonly conversation?: string | undefined;
-    readonly truncation?: string | undefined;
-    readonly reasoning?: {
-        readonly effort?: OpenAIReasoningEffort | undefined;
-    } | undefined;
-    /** Ollama extension: boolean, model-defined string, or null for model default. */
-    readonly think?: boolean | string | null | undefined;
-}
-/** Strict Ollama-documented Responses request; excludes stateful and SDK-only request fields. */
-/** Strict Ollama-documented Responses request; excludes only unsupported stateful fields. */
-type OllamaOpenAIResponsesRequest = Omit<OpenAIResponsesRequest, 'previous_response_id' | 'conversation'>;
-type OpenAIResponsesStatus = 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete';
-interface OpenAIResponsesError {
-    readonly code?: string | undefined;
-    readonly message?: string | undefined;
-    readonly [key: string]: unknown;
-}
-interface OpenAIResponsesIncompleteDetails {
-    readonly reason?: string | undefined;
-    readonly [key: string]: unknown;
-}
-interface OpenAIResponsesOutputTextContent {
-    readonly type: 'output_text';
-    readonly text: string;
-    readonly annotations?: readonly Record<string, unknown>[] | undefined;
-    readonly logprobs?: readonly Record<string, unknown>[] | undefined;
-}
-interface OpenAIResponsesOutputRefusal {
-    readonly type: 'refusal';
-    readonly refusal: string;
-}
-type OpenAIResponsesOutputContent = OpenAIResponsesOutputTextContent | OpenAIResponsesOutputRefusal;
-interface OpenAIResponsesOutputMessage {
-    readonly type: 'message';
-    readonly id?: string | undefined;
-    readonly status?: OpenAIResponsesStatus | undefined;
-    readonly role?: string | undefined;
-    readonly phase?: string | undefined;
-    readonly content: readonly OpenAIResponsesOutputContent[];
-}
-interface OpenAIResponsesOutputFunctionCall {
-    readonly type: 'function_call';
-    readonly id?: string | undefined;
-    readonly call_id?: string | undefined;
-    readonly name: string;
-    readonly arguments: string;
-    readonly status?: OpenAIResponsesStatus | undefined;
-}
-interface OpenAIResponsesOutputReasoning {
-    readonly type: 'reasoning';
-    readonly id?: string | undefined;
-    readonly status?: OpenAIResponsesStatus | undefined;
-    readonly summary?: readonly {
-        readonly type: 'summary_text';
-        readonly text: string;
-    }[] | undefined;
-    readonly text?: string | undefined;
-    readonly encrypted_content?: string | undefined;
+    /** Maps to `reasoning.effort` on the native endpoint; ignored by the chat adapter. */
+    readonly reasoning_effort?: ResponsesReasoningEffort | undefined;
+    /** Ollama-specific extension: thinking output control (boolean or model-defined level). */
+    readonly think?: ThinkValue | undefined;
 }
-type OpenAIResponsesOutputItem = OpenAIResponsesOutputMessage | OpenAIResponsesOutputFunctionCall | OpenAIResponsesOutputReasoning;
-interface OpenAIResponsesUsage {
+/** Token usage in OpenAI Responses naming. */
+interface ResponsesUsage {
     readonly input_tokens: number;
     readonly output_tokens: number;
     readonly total_tokens: number;
-    readonly input_tokens_details?: Record<string, unknown> | undefined;
-    readonly output_tokens_details?: Record<string, unknown> | undefined;
 }
-/** Non-stateful response shape for the Ollama Responses compatibility endpoint. */
-interface OpenAIResponsesResponse {
+/**
+ * Normalized, non-stateful Responses result — `output_text` is the joined
+ * text of all `output_text` content blocks, so consumers never touch the
+ * nested `output[]` structure.
+ */
+interface ResponsesCreateResponse {
     readonly id: string;
-    readonly object: 'response';
-    readonly created: number;
-    readonly created_at?: number | undefined;
-    readonly status?: OpenAIResponsesStatus | undefined;
-    readonly completed_at?: number | null | undefined;
-    readonly error?: OpenAIResponsesError | null | undefined;
-    readonly incomplete_details?: OpenAIResponsesIncompleteDetails | null | undefined;
     readonly model: string;
-    readonly output: readonly OpenAIResponsesOutputItem[];
-    readonly output_text?: string | undefined;
-    readonly previous_response_id?: string | null | undefined;
-    readonly parallel_tool_calls?: boolean | undefined;
-    readonly usage?: OpenAIResponsesUsage | undefined;
-}
-declare class OpenAIResponsesStreamError extends OllamaClientError {
-    readonly responsePayload: OpenAIResponsesResponse;
-    constructor(message: string, responsePayload: OpenAIResponsesResponse);
-}
-declare class OpenAIChatCompletionStream implements AsyncIterable<OpenAIChatCompletionChunk> {
-    private readonly source;
-    private readonly finalResultPromise;
-    private resolveFinal;
-    private rejectFinal;
-    private removeAbortListener;
-    constructor(source: AbortableAsyncIterable<SseEvent>, signal?: AbortSignal);
-    get finalResult(): Promise<OpenAIChatCompletionResponse>;
-    abort(): void;
-    [Symbol.asyncIterator](): AsyncGenerator<OpenAIChatCompletionChunk, void, undefined>;
-}
-declare class OpenAICompletionStream implements AsyncIterable<OpenAICompletionChunk> {
-    private readonly source;
-    private readonly finalResultPromise;
-    private resolveFinal;
-    private rejectFinal;
-    private removeAbortListener;
-    constructor(source: AbortableAsyncIterable<SseEvent>, signal?: AbortSignal);
-    get finalResult(): Promise<OpenAICompletionResponse>;
-    abort(): void;
-    [Symbol.asyncIterator](): AsyncGenerator<OpenAICompletionChunk, void, undefined>;
-}
-interface OpenAIResponsesEventBase {
-    readonly response_id?: string | undefined;
-    readonly sequence_number?: number | undefined;
-}
-interface OpenAIResponsesOutputTextDeltaEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.output_text.delta';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
-    readonly delta: string;
-}
-interface OpenAIResponsesOutputTextDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.output_text.done';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
-    readonly text: string;
-}
-interface OpenAIResponsesFunctionCallArgumentsDeltaEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.function_call_arguments.delta';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly delta: string;
-}
-interface OpenAIResponsesFunctionCallArgumentsDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.function_call_arguments.done';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly arguments: string;
-    readonly name?: string | undefined;
-}
-interface OpenAIResponsesReasoningTextDeltaEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.reasoning_text.delta';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
-    readonly delta: string;
-}
-interface OpenAIResponsesReasoningTextDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.reasoning_text.done';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
-    readonly text: string;
-}
-interface OpenAIResponsesReasoningSummaryPartAddedEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.reasoning_summary_part.added';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly summary_index: number;
-    readonly part: {
-        readonly type: 'summary_text';
-        readonly text: string;
-    };
-}
-interface OpenAIResponsesReasoningSummaryPartDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.reasoning_summary_part.done';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly summary_index: number;
-    readonly part: {
-        readonly type: 'summary_text';
-        readonly text: string;
-    };
-    readonly status?: 'incomplete' | undefined;
-}
-interface OpenAIResponsesReasoningSummaryTextDeltaEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.reasoning_summary_text.delta';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly summary_index: number;
+    readonly created_at: string;
+    readonly output_text: string;
+    /** Reasoning-model thinking trace, when produced with `think` enabled. */
+    readonly thinking?: string | undefined;
+    /** Parsed function calls the model requested, when `tools` were provided. */
+    readonly tool_calls?: readonly ToolCall[] | undefined;
+    readonly usage?: ResponsesUsage | undefined;
+    /** Which transport served the request — see the module doc on dual-mode. */
+    readonly transport: 'native' | 'chat-adapter';
+}
+/** Simplified streaming events from {@link ResponsesModule.stream}. */
+type ResponsesStreamEvent = {
+    readonly type: 'text_delta';
     readonly delta: string;
-}
-interface OpenAIResponsesReasoningSummaryTextDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.reasoning_summary_text.done';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly summary_index: number;
-    readonly text: string;
-}
-interface OpenAIResponsesOutputItemAddedEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.output_item.added';
-    readonly item: OpenAIResponsesOutputItem;
-    readonly output_index: number;
-}
-interface OpenAIResponsesOutputItemDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.output_item.done';
-    readonly item: OpenAIResponsesOutputItem;
-    readonly output_index: number;
-}
-interface OpenAIResponsesContentPartAddedEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.content_part.added';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
-    readonly part: OpenAIResponsesOutputContent | {
-        readonly type: string;
-        readonly [key: string]: unknown;
-    };
-}
-interface OpenAIResponsesContentPartDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.content_part.done';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
-    readonly part: OpenAIResponsesOutputContent | {
-        readonly type: string;
-        readonly [key: string]: unknown;
-    };
-}
-interface OpenAIResponsesRefusalDeltaEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.refusal.delta';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
+} | {
+    readonly type: 'thinking_delta';
     readonly delta: string;
-}
-interface OpenAIResponsesRefusalDoneEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.refusal.done';
-    readonly item_id: string;
-    readonly output_index: number;
-    readonly content_index: number;
-    readonly refusal: string;
-}
-interface OpenAIResponsesCreatedEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.created';
-    readonly response: OpenAIResponsesResponse;
-}
-interface OpenAIResponsesInProgressEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.in_progress';
-    readonly response: OpenAIResponsesResponse;
-}
-interface OpenAIResponsesQueuedEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.queued';
-    readonly response: OpenAIResponsesResponse;
-}
-interface OpenAIResponsesCompletedEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.completed' | 'response.done';
-    readonly response: OpenAIResponsesResponse;
-}
-interface OpenAIResponsesFailedEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.failed';
-    readonly response: OpenAIResponsesResponse;
-}
-interface OpenAIResponsesIncompleteEvent extends OpenAIResponsesEventBase {
-    readonly type: 'response.incomplete';
-    readonly response: OpenAIResponsesResponse;
-}
-type OpenAIResponsesStreamEvent = OpenAIResponsesOutputTextDeltaEvent | OpenAIResponsesOutputTextDoneEvent | OpenAIResponsesFunctionCallArgumentsDeltaEvent | OpenAIResponsesFunctionCallArgumentsDoneEvent | OpenAIResponsesReasoningTextDeltaEvent | OpenAIResponsesReasoningTextDoneEvent | OpenAIResponsesReasoningSummaryPartAddedEvent | OpenAIResponsesReasoningSummaryPartDoneEvent | OpenAIResponsesReasoningSummaryTextDeltaEvent | OpenAIResponsesReasoningSummaryTextDoneEvent | OpenAIResponsesOutputItemAddedEvent | OpenAIResponsesOutputItemDoneEvent | OpenAIResponsesContentPartAddedEvent | OpenAIResponsesContentPartDoneEvent | OpenAIResponsesRefusalDeltaEvent | OpenAIResponsesRefusalDoneEvent | OpenAIResponsesCreatedEvent | OpenAIResponsesInProgressEvent | OpenAIResponsesQueuedEvent | OpenAIResponsesCompletedEvent | OpenAIResponsesFailedEvent | OpenAIResponsesIncompleteEvent | {
-    readonly type: string;
-    readonly [key: string]: unknown;
+} | {
+    readonly type: 'done';
+    readonly response: ResponsesCreateResponse;
 };
-declare class OpenAIResponsesStream implements AsyncIterable<OpenAIResponsesStreamEvent> {
-    private readonly source;
-    private readonly finalResultPromise;
-    private resolveFinal;
-    private rejectFinal;
-    private removeAbortListener;
-    constructor(source: AbortableAsyncIterable<SseEvent>, signal?: AbortSignal);
-    get finalResult(): Promise<OpenAIResponsesResponse>;
-    abort(): void;
-    [Symbol.asyncIterator](): AsyncGenerator<OpenAIResponsesStreamEvent, void, undefined>;
-}
-declare class OpenAICompatClient {
-    private readonly http;
-    private readonly runner?;
-    constructor(http: HttpClient, runner?: RequestRunner | undefined);
-    private request;
-    createChatCompletion(request: OpenAIChatCompletionRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<OpenAIChatCompletionStream>;
-    createChatCompletion(request: OpenAIChatCompletionRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<OpenAIChatCompletionResponse>;
-    chatCompletions(request: OpenAIChatCompletionRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<OpenAIChatCompletionStream>;
-    chatCompletions(request: OpenAIChatCompletionRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<OpenAIChatCompletionResponse>;
-    listModels(signal?: AbortSignal): Promise<OpenAIListModelsResponse>;
-    retrieveModel(model: string, signal?: AbortSignal): Promise<OpenAIModelItem>;
-    getModel(model: string, signal?: AbortSignal): Promise<OpenAIModelItem>;
-    createCompletion(request: OpenAICompletionRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<OpenAICompletionStream>;
-    createCompletion(request: OpenAICompletionRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<OpenAICompletionResponse>;
-    completions(request: OpenAICompletionRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<OpenAICompletionStream>;
-    completions(request: OpenAICompletionRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<OpenAICompletionResponse>;
-    createEmbedding(request: OpenAIEmbeddingRequest, signal?: AbortSignal): Promise<OpenAIEmbeddingResponse>;
-    embeddings(request: OpenAIEmbeddingRequest, signal?: AbortSignal): Promise<OpenAIEmbeddingResponse>;
-    createResponses(request: OpenAIResponsesRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<OpenAIResponsesStream>;
-    createResponses(request: OpenAIResponsesRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<OpenAIResponsesResponse>;
-    responses(request: OpenAIResponsesRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<OpenAIResponsesStream>;
-    responses(request: OpenAIResponsesRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<OpenAIResponsesResponse>;
+/**
+ * Dual-mode Responses API bridge. Access via `client.responses` — see the
+ * module doc for the transport selection rules.
+ */
+declare class ResponsesModule {
+    private readonly runner;
+    constructor(runner: RequestRunner);
+    /** The request body sent to the native endpoint (also reused for streaming). */
+    private nativeBody;
+    /**
+     * Runs one Responses request, preferring the native `POST /v1/responses`
+     * endpoint and transparently re-issuing via `/api/chat` when the server
+     * answers `404` (pre-v0.13.3 Ollama without the compatibility endpoint).
+     */
+    create(req: ResponsesCreateRequest): Promise<ResponsesCreateResponse>;
+    /** Convenience: `create()` returning only the `output_text` string. */
+    createText(req: ResponsesCreateRequest): Promise<string>;
+    private createViaChatAdapter;
+    /**
+     * Streams a Responses request as simplified
+     * `{type: 'text_delta' | 'thinking_delta' | 'done'}` events. Dual-mode like
+     * {@link create}: native SSE from `/v1/responses` when available, otherwise
+     * the normalized `/api/chat` token stream. Tool calls are not delta'd —
+     * collect them from the final `done` event's `response.tool_calls`.
+     *
+     * This is a lazy async generator: nothing is sent until the first
+     * iteration, matching `for await (... of client.responses.stream(req))`
+     * intuition. The generator is also cancellable through `req.signal`.
+     */
+    stream(req: ResponsesCreateRequest): AsyncGenerator<ResponsesStreamEvent, void, void>;
 }
 
 /**
- * Anthropic Compatibility interfaces and client helpers for Ollama.
- * Ollama supports the Anthropic Messages API format.
+ * KV-prefix-preserving conversation sessions.
+ *
+ * Ollama reuses the model's KV cache across turns of a conversation by
+ * **prompt prefix matching**: if the new prompt's leading tokens are
+ * byte-identical to the previous turn's, the cached prefix is reused and
+ * only the new suffix is evaluated — surfaced by the server as
+ * `prompt_eval_cached_count`. Anything that mutates the prefix invalidates
+ * the whole cache and forces a full re-evaluation (`prompt_eval_count`
+ * spikes, latency jumps): changing the system prompt, prepending dynamic
+ * timestamps or request IDs to the conversation, or reordering past turns.
+ *
+ * `ConversationSession` makes the cache-friendly structure the default:
+ *
+ *   - The system prompt (if any) is fixed at construction and always the
+ *     first message. There is deliberately **no API to mutate it later** —
+ *     a mutable system prompt is the #1 silent KV-cache killer.
+ *   - History is append-only. Messages are never reordered, rewritten, or
+ *     re-serialized between turns — `getMessages()` copies, so external
+ *     mutation can't leak in either.
+ *   - Per-turn options (`options`, `think`, `tools`, …) ride on the request,
+ *     not the history, so changing them never disturbs the prefix.
+ *
+ * Each turn records what the server reported about the cache, so degrading
+ * hit rates (a symptom of prefix churn somewhere upstream, or a context
+ * window that no longer holds the whole history) are visible in
+ * {@link ConversationSession.cacheStats} instead of hiding in raw responses.
  */
 
-interface AnthropicCacheControl {
-    readonly type: 'ephemeral';
-    readonly ttl?: '5m' | '1h' | undefined;
-}
-interface AnthropicTextContentBlock {
-    readonly type: 'text';
-    readonly text: string;
-    readonly cache_control?: AnthropicCacheControl | undefined;
-}
-interface AnthropicImageContentBlock {
-    readonly type: 'image';
-    readonly source: {
-        readonly type: 'base64';
-        readonly media_type: string;
-        readonly data: string;
-    };
-}
-interface AnthropicToolUseContentBlock {
-    readonly type: 'tool_use';
-    readonly id: string;
-    readonly name: string;
-    readonly input: Record<string, unknown>;
-}
-interface AnthropicToolResultContentBlock {
-    readonly type: 'tool_result';
-    readonly tool_use_id: string;
-    readonly content?: string | readonly AnthropicTextContentBlock[] | undefined;
-    readonly is_error?: boolean | undefined;
-}
-interface AnthropicThinkingContentBlock {
-    readonly type: 'thinking';
-    readonly thinking: string;
-    readonly signature?: string | undefined;
-}
-interface AnthropicRedactedThinkingContentBlock {
-    readonly type: 'redacted_thinking';
-    readonly data: string;
+/** What one turn's response reported about KV-cache reuse and evaluation. */
+interface TurnCacheStats {
+    /** Prompt tokens served from the KV cache this turn. */
+    readonly cachedTokens: number;
+    /** Prompt tokens freshly evaluated this turn. */
+    readonly evaluatedTokens: number;
+    /**
+     * Cache hit rate for this turn: `cached / (cached + evaluated)`.
+     *
+     * Note the denominator adds both counters — when the *entire* prompt hits
+     * the cache, Ollama reports `prompt_eval_count: 0`, so dividing by
+     * `prompt_eval_count` alone would falsely yield a 0% hit rate on the
+     * best-case turn.
+     */
+    readonly hitRate: number;
+}
+/** Cumulative cache statistics across every completed turn so far. */
+interface CumulativeCacheStats extends TurnCacheStats {
+    /** Number of completed turns (user+assistant pairs). */
+    readonly turns: number;
+    /** Total prompt tokens across turns, cached + evaluated. */
+    readonly totalPromptTokens: number;
+}
+/** Everything one {@link ConversationSession.sendTurn} call knows. */
+interface SessionTurn {
+    /** The assistant's text reply (same value `send()` returns). */
+    readonly content: string;
+    /** What the server reported about KV-cache reuse for this turn. */
+    readonly cache: TurnCacheStats;
+    /** The full underlying `/api/chat` response (usage, durations, thinking, …). */
+    readonly response: ChatResponse;
+}
+/** Per-turn overrides — none of these touch the history prefix, so they are KV-safe. */
+interface ConversationSendOptions extends Pick<ChatRequestOptions, 'signal' | 'timeoutMs'> {
+    readonly options?: ModelOptions | undefined;
+    readonly think?: ThinkValue | undefined;
+    readonly keep_alive?: string | number | undefined;
+    readonly tools?: readonly ToolDefinition[] | undefined;
+    readonly format?: FormatOption | undefined;
 }
-type AnthropicContentBlock = AnthropicTextContentBlock | AnthropicImageContentBlock | AnthropicToolUseContentBlock | AnthropicToolResultContentBlock | AnthropicThinkingContentBlock | AnthropicRedactedThinkingContentBlock;
-interface AnthropicMessage {
-    readonly role: 'user' | 'assistant';
-    readonly content: string | readonly AnthropicContentBlock[];
+/** Static configuration for a session, fixed at construction (KV-prefix safety). */
+interface ConversationSessionOptions {
+    readonly model: string;
+    /**
+     * System prompt, pinned as the first history message for the session's
+     * whole lifetime. Avoid dynamic content here (timestamps, request IDs) —
+     * a per-call system prompt defeats prefix caching entirely.
+     */
+    readonly systemPrompt?: string | undefined;
+    /** Default `options` (sampler settings, `num_ctx`, …) applied to every turn. */
+    readonly options?: ModelOptions | undefined;
+    /** Default `think` control applied to every turn. */
+    readonly think?: ThinkValue | undefined;
+    /** Default `keep_alive` applied to every turn. */
+    readonly keep_alive?: string | number | undefined;
+    /** Default `tools` applied to every turn. */
+    readonly tools?: readonly ToolDefinition[] | undefined;
+    /** Default `format` (structured output) applied to every turn. */
+    readonly format?: FormatOption | undefined;
 }
-interface AnthropicSystemTextBlock {
-    readonly type: 'text';
-    readonly text: string;
-    readonly cache_control?: AnthropicCacheControl | undefined;
+/**
+ * A multi-turn chat session with an immutable, cache-friendly message
+ * history. Create via `client.session(...)` or construct directly:
+ *
+ * ```ts
+ * const session = client.session('llama3.1', 'You are a concise assistant.');
+ * await session.send('Hi!');        // turn 1 — cold cache
+ * await session.send('Why is the sky blue?'); // turn 2 — prefix reused
+ * session.cacheStats;               // cumulative hit rate
+ * ```
+ */
+declare class ConversationSession {
+    private readonly client;
+    private readonly config;
+    /** Ordered, append-only history. Message objects are frozen on push. */
+    private readonly history;
+    /** Mutable tallies behind the read-only {@link cacheStats} view. */
+    private readonly tallies;
+    constructor(client: OllamaClient, config: ConversationSessionOptions);
+    /** The model name this session talks to. */
+    get model(): string;
+    /** Number of completed turns. */
+    get turnCount(): number;
+    /** Cumulative KV-cache statistics across completed turns. */
+    get cacheStats(): CumulativeCacheStats;
+    /**
+     * Sends the user's message and returns the assistant's reply text —
+     * the ergonomic path. Use {@link sendTurn} when you also need the
+     * per-turn cache statistics or the raw response.
+     */
+    send(content: string, overrides?: ConversationSendOptions): Promise<string>;
+    /**
+     * Sends the user's message and returns the full turn record: reply text,
+     * per-turn KV-cache statistics, and the raw `/api/chat` response.
+     */
+    sendTurn(content: string, overrides?: ConversationSendOptions): Promise<SessionTurn>;
+    /**
+     * A defensive copy of the session history — mutating the returned array or
+     * its frozen messages has no effect on the session.
+     */
+    getMessages(): readonly Message[];
+    /**
+     * Clears the conversation back to its initial state (system prompt, zero
+     * turns, zeroed cache statistics). The next turn starts with a cold cache
+     * by definition — there is nothing upstream of it to reuse.
+     */
+    reset(): void;
 }
-type AnthropicSystem = string | readonly AnthropicSystemTextBlock[];
-interface AnthropicTool {
-    readonly name: string;
-    readonly description?: string | undefined;
-    readonly input_schema: Record<string, unknown>;
-    readonly eager_input_streaming?: boolean | undefined;
+
+/**
+ * Ergonomic System One types — key-safe generics on top of the generated
+ * contract models.
+ *
+ * The generated `SystemOneRequest` and `SystemOneResponse` (in
+ * `src/generated/models/`) use `Record<string, ...>` for the
+ * questions/answers maps. That's structurally correct but loses the
+ * connection between the question names the caller sends and the answer
+ * names they receive back — `response.answers.someRandomKey` would
+ * compile even though the caller never asked that question.
+ *
+ * This file adds a generic layer:
+ *
+ * ```ts
+ * const result = await ollama.systemOne({
+ *   model: 'tev1:4b',
+ *   state: { ticket: 'charged twice' },
+ *   questions: {
+ *     intent: { type: 'choice', ... },
+ *     urgent: { type: 'noul', ... },
+ *   },
+ * });
+ *
+ * // Key-safe: 'intent' and 'urgent' are the only valid keys.
+ * result.answers.intent  // ✓ SystemOneAnswer
+ * result.answers.urgent  // ✓ SystemOneAnswer
+ * result.answers.typo    // ✗ TypeScript error
+ * ```
+ *
+ * The generic is purely a compile-time wrapper — the runtime behavior is
+ * unchanged. The generated types remain the canonical contract; these
+ * types are an SDK-level convenience that OpenAPI cannot express.
+ *
+ * Wave 13.
+ */
+
+/**
+ * Maximum total request size, in bytes, accepted by `/v1/systemone`
+ * when the request body carries a non-empty `images` array.
+ *
+ * The Ollama server enforces this limit server-side and rejects
+ * oversized payloads with HTTP 413. The SDK's runtime also enforces
+ * it client-side (see `OllamaRuntime`'s `maxRequestBytesWithImages`
+ * handling) so the round-trip is avoided.
+ *
+ * Without images, the limit is the much smaller
+ * {@link MAX_SYSTEM_ONE_REQUEST_BYTES} (64 KiB) — the bumped
+ * images-cap exists specifically to accommodate base64-encoded image
+ * bytes shared across all questions in a single System One call.
+ */
+declare const MAX_SYSTEM_ONE_IMAGES_BYTES: number;
+/**
+ * Maximum total request size, in bytes, for `/v1/systemone` when no
+ * images are attached. The Ollama server caps the JSON-only payload
+ * at 64 KiB; the runtime enforces this client-side (see
+ * `OllamaRuntime`'s `maxRequestBytes`).
+ */
+declare const MAX_SYSTEM_ONE_REQUEST_BYTES: number;
+/**
+ * Discriminated union of the three question kinds. The upstream OpenAPI
+ * defines this inline as `oneOf` within SystemOneRequest.questions; we
+ * reconstruct it as a named type for SDK ergonomics.
+ */
+type SystemOneQuestion = SystemOneChoiceQuestion | SystemOneNoulQuestion | SystemOneScoreQuestion;
+/**
+ * Discriminated union of the three answer kinds. The upstream OpenAPI
+ * defines this inline as `oneOf` within SystemOneResponse.answers; we
+ * reconstruct it as a named type for SDK ergonomics.
+ */
+type SystemOneAnswer = SystemOneChoiceAnswer | SystemOneNoulAnswer | SystemOneScoreAnswer;
+/**
+ * Token usage for a System One call. The upstream OpenAPI defines this
+ * inline within SystemOneResponse; we reconstruct it as a named type
+ * for SDK ergonomics. Carries input_tokens and output_tokens (not
+ * prompt_tokens/completion_tokens).
+ */
+interface SystemOneUsage {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
 }
-type AnthropicToolChoice = {
-    readonly type: 'auto';
-    readonly disable_parallel_tool_use?: boolean | undefined;
-} | {
-    readonly type: 'any';
-    readonly disable_parallel_tool_use?: boolean | undefined;
-} | {
-    readonly type: 'tool';
-    readonly name: string;
-    readonly disable_parallel_tool_use?: boolean | undefined;
-} | {
-    readonly type: 'none';
+/** Map of question id → question descriptor. */
+type SystemOneQuestions = Record<string, SystemOneQuestion>;
+/**
+ * Wave 16 (P2): conditional mapping from a question type to its
+ * corresponding answer type. This gives compile-time type correlation:
+ *
+ *   choice question → choice answer
+ *   noul question   → noul answer
+ *   score question  → score answer
+ *
+ * Without this, `SystemOneAnswers<Q>` maps every key to the full
+ * `SystemOneAnswer` union, requiring manual narrowing. With this,
+ * `result.answers.myChoiceQuestion` is automatically typed as
+ * `SystemOneChoiceAnswer`.
+ */
+type AnswerFor<Q> = Q extends {
+    readonly type: 'choice';
+} ? SystemOneChoiceAnswer : Q extends {
+    readonly type: 'noul';
+} ? SystemOneNoulAnswer : Q extends {
+    readonly type: 'score';
+} ? SystemOneScoreAnswer : SystemOneAnswer;
+/**
+ * Key-safe answers map: for every question key `K` in `Q`, the response
+ * carries the answer type that corresponds to that question's type.
+ * Wave 16: now uses `AnswerFor<Q[K]>` for exact type correlation.
+ */
+type SystemOneAnswers<Q extends SystemOneQuestions = SystemOneQuestions> = {
+    readonly [K in keyof Q]: AnswerFor<Q[K]>;
 };
-interface AnthropicThinkingConfig {
-    readonly type: 'enabled' | 'disabled' | 'adaptive';
-    readonly display?: 'omitted' | 'summarized' | 'updates' | undefined;
-    /** Accepted by Ollama for compatibility but currently not enforced by the server. */
-    readonly budget_tokens?: number | undefined;
-}
-interface AnthropicOutputConfig {
-    readonly effort?: string | undefined;
+/**
+ * Generic System One request. When `Q` is provided, `questions` is typed
+ * as `Q` (the caller's specific question map) rather than the loose
+ * `Record<string, SystemOneQuestion>`. The response's `answers` will
+ * then carry the same keys.
+ *
+ * The `model`, `state`, `images`, and `keep_alive` fields are inherited
+ * from the generated base type unchanged.
+ *
+ * ## Image support
+ *
+ * The `images` field accepts up to N base64-encoded images shared by
+ * all questions in the request. Total request payload (JSON + images)
+ * must remain within {@link MAX_SYSTEM_ONE_IMAGES_BYTES} (32 MiB);
+ * requests without images are capped at
+ * {@link MAX_SYSTEM_ONE_REQUEST_BYTES} (64 KiB).
+ *
+ * Use {@link estimateSystemOneRequestBytes} for a client-side pre-flight
+ * check before sending a large multi-image batch — the runtime also
+ * enforces the limit, but the early check avoids the round-trip when
+ * the caller already knows the payload is too large.
+ *
+ * Requires Clef or Clef Flash with vision weights. URLs and data URLs
+ * are NOT supported — pre-encode the bytes to base64 before adding to
+ * the array.
+ */
+interface SystemOneRequest<Q extends SystemOneQuestions = SystemOneQuestions> extends Omit<SystemOneRequest$1, 'questions'> {
+    readonly questions: Q;
 }
-interface AnthropicMetadata {
-    readonly user_id?: string | undefined;
+/**
+ * Generic System One response. When `Q` is provided, `answers` is typed
+ * as `SystemOneAnswers<Q>` — a key-safe map matching the questions the
+ * caller asked.
+ */
+interface SystemOneResponse<Q extends SystemOneQuestions = SystemOneQuestions> extends Omit<SystemOneResponse$1, 'answers' | 'usage'> {
+    readonly answers: SystemOneAnswers<Q>;
+    readonly usage: SystemOneUsage;
 }
-interface AnthropicMessagesRequest {
-    readonly model: string;
-    readonly messages: readonly AnthropicMessage[];
-    readonly system?: AnthropicSystem | undefined;
-    readonly max_tokens?: number | undefined;
-    readonly temperature?: number | undefined;
-    readonly top_p?: number | undefined;
-    readonly top_k?: number | undefined;
-    readonly stop_sequences?: readonly string[] | undefined;
-    readonly stream?: boolean | undefined;
-    readonly tools?: readonly AnthropicTool[] | undefined;
-    readonly thinking?: AnthropicThinkingConfig | undefined;
-    readonly output_config?: AnthropicOutputConfig | undefined;
-    /**
-     * Accepted for Anthropic compatibility but currently ignored by Ollama.
-     * Tool selection cannot be forced through the Ollama compatibility endpoint.
-     */
-    readonly tool_choice?: AnthropicToolChoice | undefined;
-    /** Accepted for compatibility but currently ignored by Ollama. */
-    readonly metadata?: AnthropicMetadata | undefined;
+/**
+ * Estimate the on-the-wire byte size of a System One request body, for
+ * pre-flight size validation against {@link MAX_SYSTEM_ONE_REQUEST_BYTES}
+ * (no images) or {@link MAX_SYSTEM_ONE_IMAGES_BYTES} (with images).
+ *
+ * The estimate is conservative: it uses `JSON.stringify` length and
+ * assumes UTF-8 encoding. The actual wire size may differ slightly due
+ * to server-side JSON normalization (key ordering, whitespace), but the
+ * estimate is always within a few percent of the real payload size and
+ * is suitable for "fail fast before sending" checks.
+ *
+ * @example
+ *   ```ts
+ *   const request: SystemOneRequest = { ... };
+ *   const bytes = estimateSystemOneRequestBytes(request);
+ *   const cap = request.images?.length ? MAX_SYSTEM_ONE_IMAGES_BYTES : MAX_SYSTEM_ONE_REQUEST_BYTES;
+ *   if (bytes > cap) throw new Error(`payload ${bytes}B exceeds cap ${cap}B`);
+ *   await client.systemOne(request);
+ *   ```
+ */
+declare function estimateSystemOneRequestBytes(request: SystemOneRequest | SystemOneRequest$1): number;
+
+/**
+ * Higher-level System One decision helpers.
+ *
+ * Wave 14B: These helpers wrap the low-level `OllamaClient.systemOne()`
+ * with ergonomic APIs for the six most common decision patterns. Each
+ * helper constructs a single-question request, sends it, and extracts
+ * the typed answer — so callers don't have to deal with the question
+ * map / answer map indirection for single-decision calls.
+ *
+ * The helpers return typed results (not generic SystemOneAnswer) so
+ * callers can branch on the discriminated union without manual
+ * type narrowing.
+ *
+ * For multi-question calls (e.g. routing + urgency + difficulty in
+ * one request), use `OllamaClient.systemOne()` directly with the
+ * generic key-safe wrapper.
+ */
+
+/**
+ * Result of a choice decision: the selected option key + probability
+ * distribution + confidence.
+ */
+interface ChoiceDecision {
+    /** The selected option key (highest probability). */
+    readonly choice: string;
+    /** Probability distribution over all options. */
+    readonly probabilities: Record<string, number>;
+    /** Distribution concentration (0–1). NOT a guarantee of correctness. */
+    readonly confidence: number;
+    /** Token usage for the call. */
+    readonly usage: {
+        readonly input_tokens: number;
+        readonly output_tokens: number;
+    };
 }
-/** Strict Ollama-documented Messages request; excludes fields Ollama marks unsupported. */
-type OllamaAnthropicTextContentBlock = Omit<AnthropicTextContentBlock, 'cache_control'>;
-type OllamaAnthropicTool = Omit<AnthropicTool, 'eager_input_streaming'>;
-type OllamaAnthropicThinkingConfig = {
-    readonly type: 'enabled' | 'disabled';
-    /** Accepted by Ollama for compatibility but currently not enforced by the server. */
-    readonly budget_tokens?: number | undefined;
-};
-type OllamaAnthropicToolResultContentBlock = Omit<AnthropicToolResultContentBlock, 'content'> & {
-    readonly content?: string | readonly OllamaAnthropicTextContentBlock[] | undefined;
-};
-type OllamaAnthropicContentBlock = OllamaAnthropicTextContentBlock | AnthropicImageContentBlock | AnthropicToolUseContentBlock | OllamaAnthropicToolResultContentBlock | AnthropicThinkingContentBlock;
-type OllamaAnthropicMessage = Omit<AnthropicMessage, 'content'> & {
-    readonly content: string | readonly OllamaAnthropicContentBlock[];
-};
-type OllamaAnthropicSystemTextBlock = Omit<AnthropicSystemTextBlock, 'cache_control'>;
-type OllamaAnthropicSystem = string | readonly OllamaAnthropicSystemTextBlock[];
-/** Strict Ollama-documented Messages request; excludes unsupported caching/tool-choice metadata. */
-type OllamaAnthropicMessagesRequest = Omit<AnthropicMessagesRequest, 'messages' | 'system' | 'tools' | 'thinking' | 'tool_choice' | 'metadata'> & {
-    readonly messages: readonly OllamaAnthropicMessage[];
-    readonly system?: OllamaAnthropicSystem | undefined;
-    readonly tools?: readonly OllamaAnthropicTool[] | undefined;
-    readonly thinking?: OllamaAnthropicThinkingConfig | undefined;
-};
-interface AnthropicMessagesResponse {
-    readonly id: string;
-    readonly type: 'message';
-    readonly role: 'assistant';
-    readonly content: readonly AnthropicContentBlock[];
-    readonly model: string;
-    readonly stop_reason: string | null;
-    readonly stop_sequence?: string | null | undefined;
-    readonly usage?: {
+/**
+ * Result of a noul (yes/no) decision: the probability of true + a
+ * boolean derived from it (>= 0.5 → true).
+ */
+interface NoulDecision {
+    /** Probability of true (0–1). */
+    readonly noul: number;
+    /** Boolean decision: true if noul >= 0.5, false otherwise. */
+    readonly bool: boolean;
+    /** Token usage for the call. */
+    readonly usage: {
         readonly input_tokens: number;
         readonly output_tokens: number;
-        readonly cache_creation_input_tokens?: number | undefined;
-        readonly cache_read_input_tokens?: number | undefined;
-        readonly cache_creation?: Record<string, unknown> | undefined;
-    } | undefined;
-}
-interface AnthropicMessageStartEvent {
-    readonly type: 'message_start';
-    readonly message: AnthropicMessagesResponse;
-}
-interface AnthropicContentBlockStartEvent {
-    readonly type: 'content_block_start';
-    readonly index: number;
-    readonly content_block: AnthropicContentBlock;
-}
-type AnthropicContentBlockDelta = {
-    readonly type: 'text_delta';
-    readonly text: string;
-} | {
-    readonly type: 'input_json_delta';
-    readonly partial_json: string;
-} | {
-    readonly type: 'thinking_delta';
-    readonly thinking: string;
-} | {
-    readonly type: 'signature_delta';
-    readonly signature: string;
-};
-interface AnthropicContentBlockDeltaEvent {
-    readonly type: 'content_block_delta';
-    readonly index: number;
-    readonly delta: AnthropicContentBlockDelta;
-}
-interface AnthropicContentBlockStopEvent {
-    readonly type: 'content_block_stop';
-    readonly index: number;
-}
-interface AnthropicMessageDeltaEvent {
-    readonly type: 'message_delta';
-    readonly delta: {
-        readonly stop_reason?: string | null | undefined;
-        readonly stop_sequence?: string | null | undefined;
     };
-    readonly usage?: {
-        readonly input_tokens?: number | undefined;
-        readonly output_tokens: number;
-        readonly cache_creation_input_tokens?: number | undefined;
-        readonly cache_read_input_tokens?: number | undefined;
-        readonly cache_creation?: Record<string, unknown> | undefined;
-    } | undefined;
 }
-interface AnthropicMessageStopEvent {
-    readonly type: 'message_stop';
-}
-interface AnthropicPingEvent {
-    readonly type: 'ping';
-}
-interface AnthropicErrorEvent {
-    readonly type: 'error';
-    readonly error: {
-        readonly type: string;
-        readonly message: string;
+/**
+ * Result of a score decision: the probability-weighted average score,
+ * the legend (index → description), the probability distribution, and
+ * confidence.
+ */
+interface ScoreDecision {
+    /** Probability-weighted average of zero-based criterion indices (0 to N-1). */
+    readonly score: number;
+    /** Zero-based indices as string keys → criterion descriptions. */
+    readonly legend: Record<string, string>;
+    /** Probabilities keyed by zero-based criterion indices as strings. */
+    readonly probabilities: Record<string, number>;
+    /** Distribution concentration (0–1). NOT a guarantee of correctness. */
+    readonly confidence: number;
+    /** Token usage for the call. */
+    readonly usage: {
+        readonly input_tokens: number;
+        readonly output_tokens: number;
     };
 }
-interface AnthropicUnknownStreamEvent {
-    /** Forward-compatible event type not yet modeled by this SDK. */
-    readonly type: string;
-    readonly [key: string]: unknown;
-}
-type AnthropicMessageStreamEvent = AnthropicMessageStartEvent | AnthropicContentBlockStartEvent | AnthropicContentBlockDeltaEvent | AnthropicContentBlockStopEvent | AnthropicMessageDeltaEvent | AnthropicMessageStopEvent | AnthropicPingEvent | AnthropicErrorEvent | AnthropicUnknownStreamEvent;
-declare class AnthropicMessagesStream implements AsyncIterable<AnthropicMessageStreamEvent> {
-    private readonly source;
-    private readonly finalResultPromise;
-    private resolveFinal;
-    private rejectFinal;
-    private removeAbortListener;
-    constructor(source: AbortableAsyncIterable<SseEvent>, signal?: AbortSignal);
-    get finalResult(): Promise<AnthropicMessagesResponse>;
-    abort(): void;
-    [Symbol.asyncIterator](): AsyncGenerator<AnthropicMessageStreamEvent, void, undefined>;
-}
-declare class AnthropicCompatClient {
-    private readonly http;
-    private readonly runner?;
-    constructor(http: HttpClient, runner?: RequestRunner | undefined);
-    private request;
-    createMessage(request: AnthropicMessagesRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<AnthropicMessagesStream>;
-    createMessage(request: AnthropicMessagesRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<AnthropicMessagesResponse>;
-    createMessage(request: AnthropicMessagesRequest, signal?: AbortSignal): Promise<AnthropicMessagesResponse | AnthropicMessagesStream>;
-    messages(request: AnthropicMessagesRequest & {
-        stream: true;
-    }, signal?: AbortSignal): Promise<AnthropicMessagesStream>;
-    messages(request: AnthropicMessagesRequest & {
-        stream?: false | undefined;
-    }, signal?: AbortSignal): Promise<AnthropicMessagesResponse>;
-    messages(request: AnthropicMessagesRequest, signal?: AbortSignal): Promise<AnthropicMessagesResponse | AnthropicMessagesStream>;
+/**
+ * Result of a ranking call: candidates sorted by score (highest first),
+ * each with its score and probability distribution.
+ */
+interface RankResult<T extends string> {
+    readonly candidate: T;
+    readonly score: number;
+    readonly confidence: number;
 }
+/**
+ * Higher-level System One decision helpers.
+ *
+ * Create via `createDecision(client)` or access via `client.decision`
+ * (if the accessor is wired). Each helper constructs a single-question
+ * System One request and extracts the typed answer.
+ *
+ * Example:
+ * ```ts
+ * const decision = createDecision(client);
+ * const result = await decision.choice({
+ *   model: 'tev1:4b',
+ *   state: 'Customer was charged twice',
+ *   instructions: 'What is the primary intent?',
+ *   criteria: {
+ *     refund: 'Customer wants a refund',
+ *     duplicate_charge: 'Customer reports multiple charges',
+ *     cancellation: 'Customer wants to cancel',
+ *   },
+ * });
+ * console.log(result.choice); // 'duplicate_charge'
+ * console.log(result.confidence); // 0.89
+ * ```
+ */
+interface Decision {
+    /**
+     * Ask a single choice question. Returns the selected option + full
+     * probability distribution + confidence.
+     *
+     * Use for: routing, classification, model selection, tool selection,
+     * category assignment — any "which one?" decision with bounded options.
+     */
+    choice(params: {
+        model: string;
+        state: SystemOneContent;
+        instructions: SystemOneContent;
+        criteria: Record<string, string | null>;
+        images?: string[];
+        keepAlive?: string | number;
+    }): Promise<ChoiceDecision>;
+    /**
+     * Ask a single yes/no (noul) question. Returns the probability of
+     * true (0–1) + a boolean derived from it (>= 0.5 → true).
+     *
+     * Use for: gating, verification, safety checks, eligibility, prompt-
+     * injection detection — any "is this true?" decision.
+     */
+    noul(params: {
+        model: string;
+        state: SystemOneContent;
+        instructions: SystemOneContent;
+        images?: string[];
+        keepAlive?: string | number;
+    }): Promise<NoulDecision>;
+    /**
+     * Ask a single score question. Returns the probability-weighted
+     * average score + legend + probability distribution + confidence.
+     *
+     * Use for: severity, priority, difficulty, relevance, quality — any
+     * "how strongly does this fit this ordered rubric?" decision.
+     */
+    score(params: {
+        model: string;
+        state: SystemOneContent;
+        instructions: SystemOneContent;
+        /** Ordered criteria from lowest (index 0) to highest. 2–26 items. */
+        criteria: string[];
+        images?: string[];
+        keepAlive?: string | number;
+    }): Promise<ScoreDecision>;
+    /**
+     * Route a request to one of N named options. Convenience wrapper
+     * around `choice()` that returns just the selected route name.
+     *
+     * Use for: workflow routing, model routing, agent dispatch, tool
+     * selection — any "which handler?" decision.
+     */
+    route<T extends string>(params: {
+        model: string;
+        state: SystemOneContent;
+        instructions: SystemOneContent;
+        criteria: Record<T, string | null>;
+        images?: string[];
+        keepAlive?: string | number;
+    }): Promise<{
+        readonly route: T;
+        readonly confidence: number;
+    }>;
+    /**
+     * Verify whether a claim is supported by evidence. Convenience
+     * wrapper around `noul()` that returns a boolean + the probability
+     * of true (not System One's confidence score — noul answers don't
+     * carry a separate confidence field).
+     *
+     * Use for: evidence verification, safety gates, prompt-injection
+     * detection, compliance checks — any "is this claim true given
+     * this evidence?" decision.
+     */
+    verify(params: {
+        model: string;
+        claim: SystemOneContent;
+        evidence: SystemOneContent;
+        instructions?: SystemOneContent;
+        images?: string[];
+        keepAlive?: string | number;
+    }): Promise<{
+        readonly verified: boolean;
+        readonly probability: number;
+    }>;
+    /**
+     * Rank candidates by score. Sends one System One call per candidate
+     * (parallelized), then sorts by score descending.
+     *
+     * Use for: semantic reranking, candidate ranking, priority scoring,
+     * relevance scoring — any "which of these is best?" decision where
+     * each candidate is scored independently against the same rubric.
+     *
+     * Note: this makes N parallel requests (one per candidate). For
+     * large candidate sets, consider batching or using a single choice
+     * question with all candidates as options instead.
+     */
+    rank<T extends string>(params: {
+        model: string;
+        instructions: SystemOneContent;
+        /** Ordered criteria from lowest (index 0) to highest. 2–26 items. */
+        criteria: string[];
+        candidates: ReadonlyArray<{
+            readonly id: T;
+            readonly state: SystemOneContent;
+        }>;
+        images?: string[];
+        keepAlive?: string | number;
+    }): Promise<ReadonlyArray<RankResult<T>>>;
+}
+/** Create a Decision helper bound to an OllamaClient. */
+declare function createDecision(client: OllamaClient): Decision;
 
 /**
  * High-level Ollama client — the original, hand-written API surface.
@@ -1352,6 +1419,12 @@ declare class OllamaClient {
      * `OLLAMA_API_KEY`), independent of whether `config.endpoints` was used instead.
      */
     private readonly cloudApiKey;
+    /** Configured `defaultContextLength` — injected as `num_ctx` when a request omits it. */
+    private readonly defaultContextLength;
+    /** Configured `contextWarningThreshold` (default 0.9). */
+    private readonly contextWarningThreshold;
+    /** Configured overflow policy — `'warn'` (default) or `'throw'`. */
+    private readonly onContextOverflow;
     constructor(config?: OllamaClientConfig);
     get modelsClient(): ModelsClient;
     /**
@@ -1362,23 +1435,94 @@ declare class OllamaClient {
      * API with the generated `NativeApi` / `OpenAIApi` / `AnthropicApi`
      * surface without configuring two separate HttpClient instances.
      *
-     * The returned runtime is bound to the registry's first candidate
-     * endpoint (or the resolved single-endpoint config if no `endpoints`
-     * array was provided). For multi-endpoint configs that need per-call
-     * routing, prefer constructing `OllamaRuntime` directly with a
-     * specific HttpClient:
-     *
-     * ```ts
-     * const http = new HttpClient({ baseUrl: 'http://host-a:11434' });
-     * const runtime = new OllamaRuntime({ http });
-     * const api = new NativeApi(runtime);
-     * ```
+     * Wave 14: the runtime now participates in multi-endpoint failover.
+     * Each request is routed through this client's `executeWithFailover`
+     * machinery via a {@link FailoverHttpClient} wrapper. If the first
+     * candidate endpoint is down, requests automatically fail over to
+     * the next healthy candidate — matching the behavior of the
+     * hand-written OllamaClient methods (chat, generate, etc.).
      *
      * The runtime is cached on first call — subsequent calls return the
-     * same instance.
+     * same instance. The `FailoverHttpClient` holds a reference to this
+     * client, so it always sees the current endpoint registry state.
      */
     get runtime(): OllamaRuntime;
     private _runtime;
+    /**
+     * Lazily-constructed `NativeApi` bound to this client's runtime. Exposes
+     * the full generated native API surface (chat, generate, embed, systemOne,
+     * etc.) with contract-driven types and runtime enforcement.
+     *
+     * Wave 13: `systemOne()` delegates to this accessor.
+     */
+    get native(): NativeApi;
+    private _nativeApi;
+    /**
+     * Higher-level System One decision helpers (Wave 14B).
+     *
+     * Ergonomic wrappers around `systemOne()` for the six most common
+     * decision patterns: `choice()`, `noul()`, `score()`, `route()`,
+     * `verify()`, `rank()`. Each constructs a single-question request
+     * and extracts the typed answer.
+     *
+     * ```ts
+     * const result = await client.decision.choice({
+     *   model: 'tev1:4b',
+     *   state: 'Customer was charged twice',
+     *   instructions: 'What is the primary intent?',
+     *   criteria: {
+     *     refund: 'Customer wants a refund',
+     *     duplicate_charge: 'Customer reports multiple charges',
+     *   },
+     * });
+     * console.log(result.choice); // 'duplicate_charge'
+     * console.log(result.confidence); // 0.89
+     * ```
+     */
+    get decision(): Decision;
+    private _decision;
+    /**
+     * Ergonomic OpenAI Responses API bridge (`client.responses.create()` /
+     * `.stream()`). Dual-mode transport: prefers the native `POST
+     * /v1/responses` endpoint (Ollama ≥ v0.13.3) and transparently re-issues via
+     * `/api/chat` when the server answers 404, so migrating OpenAI code works
+     * unchanged against older servers. See `src/responses.ts`.
+     */
+    get responses(): ResponsesModule;
+    private _responses;
+    /**
+     * Starts a KV-prefix-preserving multi-turn conversation session.
+     *
+     * ```ts
+     * const session = client.session('llama3.1', 'You are a concise assistant.');
+     * const reply = await session.send('Hi!');
+     * const detail = await session.sendTurn('Why is the sky blue?');
+     * detail.cache.hitRate; // per-turn KV-cache hit rate
+     * session.cacheStats; // cumulative stats across turns
+     * ```
+     *
+     * Accepts either `(model, systemPrompt?)` or a full options object
+     * (`{ model, systemPrompt, options, think, keep_alive, tools }`). See
+     * `src/conversation.ts` for why the system prompt is pinned for the
+     * session's lifetime.
+     */
+    session(model: string, systemPrompt?: string): ConversationSession;
+    session(options: ConversationSessionOptions): ConversationSession;
+    /**
+     * Context-window pre-flight enforcement — see `src/context-safety.ts` and
+     * the `defaultContextLength` / `onContextOverflow` config docs. Logs a
+     * warning (default) or throws client-side when the estimated prompt size
+     * is close to / beyond the effective context window.
+     */
+    private enforceContextSafety;
+    /**
+     * Returns `options` with `num_ctx` injected from the client's
+     * `defaultContextLength` when the request didn't set one — making the
+     * effective context window explicit on the wire instead of relying on
+     * Ollama's silently-truncating server default. Returns the original
+     * reference when there's nothing to inject (the common case).
+     */
+    private injectDefaultContextLength;
     /**
      * Fail-fast guard for `format` (structured output) requests: throws before any network
      * call if the candidate endpoint is inferred as Ollama Cloud, which does not currently
@@ -1458,6 +1602,50 @@ declare class OllamaClient {
     readonly version: () => Promise<VersionResponse>;
     readonly createBlob: (digest: string, data: BinaryBody) => Promise<void>;
     readonly checkBlob: (digest: string) => Promise<boolean>;
+    /**
+     * Immediately unloads `model` from VRAM. Convenience alias for
+     * {@link ModelsClient.unload} — see that method for the full
+     * lifecycle contract.
+     */
+    readonly unloadModel: (model: string) => Promise<void>;
+    /**
+     * Pre-loads and pins `model` into VRAM indefinitely. Convenience
+     * alias for {@link ModelsClient.pin} — see that method for the
+     * full lifecycle contract.
+     */
+    readonly pinModel: (model: string) => Promise<void>;
+    /**
+     * Ollama's System One decision layer (`POST /v1/systemone`) — evaluates
+     * 1–64 typed questions (choice, noul, or score) against a provided state
+     * and returns typed answers with probabilities and confidence.
+     *
+     * Local-only; requires Ollama >= 0.35.0. The runtime enforces the
+     * version constraint automatically (lazily fetching `/api/version` when
+     * `enforceVersion` is `'auto'` or `'strict'`) and rejects cloud-mode
+     * calls. Request size is checked client-side: 64 KiB without images,
+     * 32 MiB with images.
+     *
+     * The generic `Q` parameter captures the caller's question map at
+     * compile time, giving key-safe answer access:
+     *
+     * ```ts
+     * const result = await ollama.systemOne({
+     *   model: 'tev1:4b',
+     *   state: { ticket: 'Customer was charged twice' },
+     *   questions: {
+     *     intent: { type: 'choice', instructions: '...', criteria: { ... } },
+     *     urgent: { type: 'noul', instructions: '...' },
+     *   },
+     * });
+     * result.answers.intent  // ✓ SystemOneAnswer (choice)
+     * result.answers.urgent  // ✓ SystemOneAnswer (noul)
+     * result.answers.typo    // ✗ TypeScript error
+     * ```
+     *
+     * For the low-level generated API (without the generic wrapper), use
+     * `client.native.systemOne(request)` directly.
+     */
+    systemOne<Q extends SystemOneQuestions = SystemOneQuestions>(request: SystemOneRequest<Q>): Promise<SystemOneResponse<Q>>;
     /**
      * Ollama's hosted web search tool (`POST https://ollama.com/api/web_search`) — a fixed
      * Ollama Cloud service, unrelated to `config.endpoints`/`baseUrl` and not proxied
@@ -1473,6 +1661,45 @@ declare class OllamaClient {
      * which applies identically here.
      */
     webFetch(req: WebFetchRequestOptions): Promise<WebFetchResponse>;
+    /**
+     * Ollama Cloud usage statistics (`GET https://ollama.com/api/usage`) — request counts,
+     * USD spend, and token totals (including cached input tokens) for cloud inference,
+     * web search, and web fetch, bucketed by hour (`range: '24h'`) or day (`'7d'`/`'30d'`).
+     *
+     * See {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry
+     * behavior, which applies identically here. Query parameters mirror the official
+     * endpoint: `range` (`'24h' | '7d' | '30d'`, server default `'7d'`) and `scope`
+     * (`'self' | 'team'`, server default `'self'`; team scope requires a team admin).
+     * Omitted options are left unset so the server applies its own defaults.
+     *
+     * ```ts
+     * const usage = await client.usage({ range: '24h' });
+     * console.log(usage.totals.request_count, usage.totals.usage_usd);
+     * for (const bucket of usage.buckets) {
+     *   if (bucket.partial) continue; // current hour, still in progress
+     *   // ...
+     * }
+     * ```
+     */
+    usage(req?: UsageRequestOptions): Promise<UsageResponse>;
+    /**
+     * Ollama Cloud balance (`GET https://ollama.com/api/balance`) — remaining included
+     * and purchased usage credits. The included balance is either a plan-period credit
+     * object (`balance_usd`/`allowance_usd`/`period`) or, on legacy plans, session/weekly
+     * percentage limits; the shape is discriminated at runtime by the server response.
+     * See {@link OllamaClient.webSearch} for the cloud-endpoint/auth/timeout/retry
+     * behavior, which applies identically here.
+     *
+     * ```ts
+     * const balance = await client.balance();
+     * if ('balance_usd' in balance.included) {
+     *   console.log(balance.included.balance_usd, balance.purchased.balance_usd);
+     * } else {
+     *   console.log(balance.included.session.remaining_percent, '% of session limit left');
+     * }
+     * ```
+     */
+    balance(req?: BalanceRequestOptions): Promise<BalanceResponse>;
     /**
      * Runs `operation` against the fixed Ollama Cloud host with this client's default
      * timeout and retry policy — the same primitives `executeWithFailover` uses, minus the
@@ -1499,6 +1726,269 @@ interface TimeoutSignal {
  */
 declare function createTimeoutSignal(timeoutMs?: number, userSignal?: AbortSignal): TimeoutSignal;
 
+/**
+ * Standalone fetch-with-backoff helper.
+ *
+ * Ollama's server caps in-flight work via `OLLAMA_MAX_QUEUE` (default
+ * 512); when the queue saturates, excess requests are rejected with
+ * HTTP **503 Service Unavailable**. The same retry discipline applies
+ * to **429 Too Many Requests** for rate-limited cloud endpoints.
+ *
+ * Callers running parallel agentic swarms (multi-turn tool loops,
+ * 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 helper is intentionally standalone: it works with any
+ * `fetch`-shaped function (browser `globalThis.fetch`, `undici`, an
+ * Edge runtime polyfill, or a `vi.fn()` mock) and does not depend on
+ * the wider `OllamaClient` / `HttpClient` machinery. Use it when you
+ * want the SDK's retry ergonomics on raw HTTP traffic that doesn't go
+ * through `OllamaClient` — for example, when calling the OpenAI / Anthropic
+ * compatibility bridges directly, or when talking to a sibling Ollama
+ * instance outside the configured endpoint registry.
+ *
+ * For SDK-routed traffic (`client.chat`, `client.generate`, …),
+ * retry/backoff is already applied automatically by the transport
+ * layer; you do NOT need to wrap those calls in `fetchWithBackoff`.
+ */
+
+/**
+ * Configuration for {@link fetchWithBackoff}.
+ *
+ * All fields optional; sensible defaults are provided.
+ */
+interface FetchWithBackoffConfig {
+    /**
+     * Maximum number of retry attempts after the initial request.
+     * Defaults to `3` (i.e. up to 4 total HTTP requests).
+     */
+    readonly maxRetries?: number | undefined;
+    /**
+     * Backoff tuning. Defaults to {@link DEFAULT_BACKOFF}
+     * (`initialDelayMs: 500`, `maxDelayMs: 30_000`, `backoffFactor: 2`).
+     */
+    readonly backoff?: BackoffOptions | undefined;
+    /**
+     * Optional callback fired before each retry sleep. Useful for
+     * logging, OpenTelemetry span events, or surfacing the
+     * backoff in observability dashboards.
+     *
+     * 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).
+     */
+    readonly onRetry?: ((attempt: number, status: number, delayMs: number) => void) | undefined;
+    /**
+     * Optional `AbortSignal` forwarded to the underlying `fetch`.
+     * Aborting mid-backoff cancels the sleep and rejects with an
+     * `AbortError`-shaped error (the same shape `fetch` itself
+     * rejects with on abort).
+     */
+    readonly signal?: AbortSignal | undefined;
+    /**
+     * Optional `fetch` implementation to use. Defaults to
+     * `globalThis.fetch`. Pass an explicit implementation when
+     * running in environments without a global `fetch` (legacy
+     * Node.js, custom sandboxes), or to inject a mock for testing.
+     */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+}
+/**
+ * HTTP statuses that trigger a retry by default. Both indicate
+ * transient, server-side saturation — the queue is full and the
+ * request is rejected without consuming inference resources.
+ *
+ *   - `503 Service Unavailable` — Ollama queue saturated
+ *     (`OLLAMA_MAX_QUEUE` exceeded).
+ *   - `429 Too Many Requests` — rate limit hit (typically Ollama
+ *     Cloud endpoints).
+ */
+declare const RETRYABLE_STATUS_CODES: ReadonlySet<number>;
+/**
+ * Default retry configuration used when {@link FetchWithBackoffConfig}
+ * is omitted entirely. Matches the SDK's internal transport defaults
+ * so consumers see identical retry behavior whether they go through
+ * `OllamaClient` or call `fetchWithBackoff` directly.
+ */
+declare const DEFAULT_FETCH_BACKOFF_CONFIG: {
+    readonly maxRetries: 3;
+};
+/**
+ * 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).
+ *
+ * The wrapper:
+ *   - forwards `input`/`init` unchanged to every attempt,
+ *   - sleeps before each retry using the configured backoff,
+ *   - retries up to `maxRetries` times (default 3), then returns the
+ *     final `Response` (whatever its status) so the caller can
+ *     branch on it,
+ *   - rethrows network errors (TypeError under WHATWG fetch) only
+ *     after exhausting retries — intermediate attempts also sleep,
+ *   - honors `AbortSignal` for both the underlying `fetch` and the
+ *     sleep between retries.
+ *
+ * @example
+ *   ```ts
+ *   const res = await fetchWithBackoff(
+ *     'http://localhost:11434/api/chat',
+ *     { method: 'POST', body: JSON.stringify(payload) },
+ *     {
+ *       maxRetries: 5,
+ *       onRetry: (attempt, status, delayMs) =>
+ *         console.warn(`retry ${attempt} (HTTP ${status}) in ${delayMs}ms`),
+ *     },
+ *   );
+ *   if (!res.ok) throw new Error(`chat failed: HTTP ${res.status}`);
+ *   ```
+ */
+declare function fetchWithBackoff(input: string | URL | Request, init?: RequestInit | undefined, config?: FetchWithBackoffConfig): Promise<Response>;
+
+/**
+ * VRAM lifecycle helpers — ergonomic `keep_alive` primitives.
+ *
+ * Ollama's `keep_alive` parameter (accepted by `/api/generate`,
+ * `/api/chat`, `/api/embed`, `/api/embeddings`, and `/v1/systemone`)
+ * controls how long a model remains resident in VRAM after a request
+ * completes. The upstream spec defines four operational semantics:
+ *
+ *   - **Duration string** (`"5m"`, `"10s"`, `"24h"`) — explicit window.
+ *   - **Integer seconds** (`3600`, `300`) — explicit window in seconds.
+ *   - **Indefinite pinning** (`-1` or `"-1m"`) — keep the model
+ *     permanently resident in VRAM until the server is restarted or
+ *     an explicit `0` request is made. Useful for hot-loop inference
+ *     where load latency dominates.
+ *   - **Immediate eviction** (`0` or `"0s"`) — unload the model from
+ *     VRAM as soon as the response is finalized. Frees GPU memory
+ *     for the next pipeline (e.g. swap a vision model out before
+ *     loading an LLM).
+ *
+ * These primitives let callers express VRAM-lifecycle intent with
+ * readable names instead of magic integers, while preserving full
+ * backward compatibility with raw `string | number` values.
+ *
+ * See: https://github.com/ollama/ollama/blob/main/docs/faq.md
+ *      #how-do-i-keep-a-model-loaded-in-memory-or-make-it-unload-immediately
+ */
+/**
+ * Sentinel value that, when passed as `keep_alive`, instructs the
+ * server to evict the model from VRAM as soon as the in-flight
+ * request finalizes its response. Equivalent to passing `0` or
+ * `"0s"`.
+ */
+declare const KEEP_ALIVE_UNLOAD: 0;
+/**
+ * Sentinel value that, when passed as `keep_alive`, instructs the
+ * server to keep the model resident in VRAM indefinitely (until
+ * the server is restarted or an explicit `0` request arrives).
+ * Equivalent to passing `-1` or `"-1m"`.
+ */
+declare const KEEP_ALIVE_INDEFINITE: -1;
+/**
+ * Ergonomic union for the `keep_alive` field on chat/generate/embed/
+ * embeddings/System One requests.
+ *
+ * Accepts every upstream-supported shape plus two SDK-level sugar
+ * literals:
+ *
+ *   - `'unload'` — same as `0`; frees GPU VRAM after this request.
+ *   - `'indefinite'` — same as `-1`; pins the model in VRAM until
+ *     an explicit unload.
+ *
+ * Use {@link normalizeKeepAlive} to convert this into the raw
+ * `string | number` shape the wire expects.
+ */
+type KeepAlive = string | number | 'unload' | 'indefinite';
+/**
+ * Convert a {@link KeepAlive} value into the raw `string | number`
+ * shape Ollama's REST API expects.
+ *
+ *   - `'unload'`     → `0`    (immediate eviction)
+ *   - `'indefinite'` → `-1`   (perpetual pinning)
+ *   - everything else is passed through unchanged
+ *
+ * Returns `undefined` for `undefined` input so callers can pipe
+ * optional fields straight through without conditional spreads.
+ *
+ * @example
+ *   normalizeKeepAlive('unload')      // → 0
+ *   normalizeKeepAlive('indefinite')   // → -1
+ *   normalizeKeepAlive('5m')          // → '5m'
+ *   normalizeKeepAlive(3600)          // → 3600
+ *   normalizeKeepAlive(undefined)     // → undefined
+ */
+declare function normalizeKeepAlive(keepAlive: KeepAlive | undefined): string | number | undefined;
+/**
+ * Type guard: `true` when the value is one of the SDK-level sugar
+ * literals (`'unload'` or `'indefinite'`). Useful for callers that
+ * want to branch on intent rather than magic integers.
+ */
+declare function isKeepAliveSugar(value: KeepAlive | unknown): value is 'unload' | 'indefinite';
+
+/**
+ * `done_reason` decoder helpers — graceful handling of upstream
+ * variance in the `done_reason` field returned by `/api/chat` and
+ * `/api/generate`.
+ *
+ * The Ollama OpenAPI documents `done_reason` as a free-form string,
+ * but the values actually observed on the wire fall into a small,
+ * stable set:
+ *
+ *   - `"stop"`      — natural stop token hit or end-of-text.
+ *   - `"length"`    — `num_predict` ceiling reached mid-generation.
+ *   - `"load"`      — model load event (seen in streaming chunks
+ *                     before the first token is generated; the
+ *                     server reports `done: true` with `done_reason:
+ *                     'load'` to indicate the load phase completed).
+ *   - `"unload"`    — model unloaded (seen after a `keep_alive: 0`
+ *                     request finalizes the unload).
+ *
+ * The SDK accepts any string for `done_reason` (so unknown values
+ * don't cause runtime errors — the conformance-test failure mode
+ * the Wave 13 CI run flagged). These helpers give callers who want
+ * to narrow on the known set a type-safe way to do so.
+ *
+ * See: https://github.com/ollama/ollama/blob/main/docs/api.md
+ */
+/**
+ * The set of `done_reason` values Ollama documents and emits in
+ * practice. Unknown upstream additions pass through as plain
+ * strings — use {@link isKnownDoneReason} to narrow.
+ */
+type KnownDoneReason = 'stop' | 'length' | 'load' | 'unload';
+/**
+ * Set of known `done_reason` literals, exposed for callers building
+ * exhaustive `switch` statements or runtime validation tables.
+ */
+declare const KNOWN_DONE_REASONS: ReadonlySet<KnownDoneReason>;
+/**
+ * Type guard: `true` when `value` is one of the documented
+ * `done_reason` literals. Use this to safely narrow from
+ * `string | undefined` to {@link KnownDoneReason} before a
+ * `switch` block.
+ *
+ * @example
+ *   ```ts
+ *   if (isKnownDoneReason(res.done_reason)) {
+ *     switch (res.done_reason) {
+ *       case 'stop':   // …
+ *       case 'length': // …
+ *       case 'load':   // …
+ *       case 'unload': // …
+ *     }
+ *   } else {
+ *     // forward-compat: an unknown reason we didn't list
+ *   }
+ *   ```
+ */
+declare function isKnownDoneReason(value: string | undefined | null): value is KnownDoneReason;
+
 /**
  * Normalization mappers and aggregators for Ollama streaming responses.
  */
@@ -1509,9 +1999,27 @@ declare function normalizeProgressStream(source: AbortableAsyncIterable<Progress
 
 /**
  * NDJSON (newline-delimited JSON) stream reader for native fetch Response bodies.
+ *
+ * Ollama's streaming endpoints (chat / generate / pull / push / create)
+ * emit newline-delimited JSON objects. Each line is a complete JSON
+ * document. The transport is chunked HTTP with status 200 OK — meaning
+ * the HTTP status never changes mid-stream even when the server
+ * encounters an error after generation has started.
+ *
+ * Instead, Ollama emits a final JSON frame of the form
+ * `{"error": "..."}` and closes the stream. This reader detects such
+ * in-band error frames and throws {@link OllamaStreamError} immediately,
+ * so callers don't see the error message bleed into the assistant's
+ * content stream as garbage tokens.
  */
 /**
  * Parses a byte stream from fetch body into an async generator of typed JSON chunks.
+ *
+ * Throws {@link OllamaStreamError} immediately upon encountering an
+ * in-band `{"error": "..."}` frame. The thrown error carries an empty
+ * `partialContent` (this low-level parser does not accumulate content;
+ * the higher-level aggregator in `streaming/normalize.ts` is the
+ * right place to surface partial content if needed).
  */
 declare function parseNdjsonStream<T>(stream: ReadableStream<Uint8Array>): AsyncGenerator<T, void, undefined>;
 
@@ -1653,6 +2161,184 @@ interface DefineToolOptions<TParams, TResult> {
  */
 declare function defineTool<TParams, TResult>(options: DefineToolOptions<TParams, TResult>): Tool<TParams, TResult>;
 
+/**
+ * Tool-call streaming accumulator — defensive merge logic for
+ * `message.tool_calls` arrays that arrive across multiple NDJSON
+ * chunks.
+ *
+ * ## When this matters
+ *
+ * Ollama's **native `/api/chat`** streaming protocol emits
+ * `message.tool_calls` as a complete JSON array (with parsed-object
+ * `arguments`, not stringified deltas) in a single `done: true` chunk.
+ * For native streaming, the accumulator here is mostly a no-op —
+ * one chunk carries the full array, the next chunk has nothing.
+ *
+ * The accumulator becomes load-bearing in three scenarios:
+ *
+ *   1. **OpenAI-compat streaming** (`/v1/chat/completions` with
+ *      `stream: true`): tool call arguments come as string deltas
+ *      spread across multiple chunks, identified by `index`. The
+ *      compat layer at `src/integrations/openai.ts` already does
+ *      its own per-index accumulation; this utility exists for
+ *      callers who want the same logic on raw NDJSON chunks.
+ *
+ *   2. **Defensive native streaming**: although the documented
+ *      Ollama behavior is "tool_calls arrive in the final chunk",
+ *      a future server version could legitimately stream them
+ *      incrementally. The SDK shouldn't crash or produce
+ *      duplicates if that happens.
+ *
+ *   3. **Caller-side buffering**: agent loops that consume
+ *      `OllamaStream` events directly may want to buffer tool-call
+ *      deltas themselves rather than trust the SDK's aggregator —
+ *      this utility gives them a typed, tested building block.
+ *
+ * ## Merge semantics
+ *
+ * Two `ToolCall` entries are considered "the same call" when they
+ * share the same `id` (the SDK-synthesized stable identifier — see
+ * `src/tools/tool-call-id.ts`), OR when they're at the same array
+ * position and neither has an `id`. When two same-call entries are
+ * merged:
+ *
+ *   - `function.name` — the later chunk's name wins (the model may
+ *     emit the name in a later chunk after an initial empty one).
+ *   - `function.arguments` — the two objects are merged with
+ *     spread semantics: `{...earlier, ...later}`. This handles
+ *     the case where the model emits arguments incrementally as
+ *     partial JSON objects (which is non-standard but seen in some
+ *     open-weights fine-tunes).
+ *
+ * For arguments-as-string deltas (the OpenAI-compat case), the
+ * accumulator concatenates the strings rather than merging — see
+ * {@link mergeToolCallArgumentsString}.
+ */
+
+/**
+ * Determine whether two `ToolCall` entries refer to the same logical
+ * call (and should therefore be merged rather than appended).
+ *
+ * Returns `true` when:
+ *   - both have an `id` and the ids match, OR
+ *   - neither has an `id` and they're at the same array index
+ *     (caller is responsible for the index check — this helper
+ *     only handles the id case).
+ */
+declare function isSameToolCall(a: ToolCall, b: ToolCall, aIndex?: number, bIndex?: number): boolean;
+/**
+ * Merge two `ToolCall` entries that refer to the same logical call.
+ *
+ * The later chunk's `function.name` wins when present; otherwise the
+ * earlier one's name is preserved. The two `arguments` objects are
+ * merged with spread semantics (`{...earlier, ...later}`), which
+ * handles the (non-standard but observed) case where the model
+ * emits arguments as partial JSON objects across chunks.
+ *
+ * For arguments-as-string deltas (OpenAI-compat streaming), use
+ * {@link mergeToolCallArgumentsString} instead.
+ */
+declare function mergeToolCall(earlier: ToolCall, later: ToolCall): ToolCall;
+/**
+ * Merge two `ToolCall` entries where `function.arguments` is a JSON
+ * string (the OpenAI-compat streaming format), concatenating the
+ * string deltas rather than spreading objects.
+ *
+ * Returns a `ToolCall` whose `function.arguments` is the
+ * concatenated string. The caller is responsible for JSON-parsing
+ * the final string when the stream completes.
+ */
+declare function mergeToolCallArgumentsString(earlier: ToolCall, later: ToolCall): ToolCall;
+/**
+ * Defensive accumulator for `message.tool_calls` arrays that arrive
+ * across multiple NDJSON chunks. Used internally by
+ * `aggregateChat` in `src/streaming/normalize.ts` so the SDK doesn't
+ * produce duplicate tool_call entries if a future server version
+ * starts streaming them incrementally.
+ *
+ * The merge strategy is:
+ *
+ *   - For each tool call in the new chunk, check whether an existing
+ *     entry matches (by `id` if both have one, by array position
+ *     otherwise).
+ *   - If a match is found, merge the two entries via
+ *     {@link mergeToolCall}.
+ *   - If no match is found, append the new entry.
+ *
+ * This preserves the documented native Ollama behavior (tool_calls
+ * arrive complete in one chunk → no merge happens, just one append)
+ * while being defensive against incremental streaming.
+ *
+ * @example
+ *   ```ts
+ *   const acc = new ToolCallAccumulator();
+ *   acc.process([
+ *     { function: { name: 'get_weather', arguments: { city: 'Tokyo' } } },
+ *   ]);
+ *   acc.process([
+ *     { function: { name: 'get_weather', arguments: { unit: 'celsius' } } },
+ *   ]);
+ *   const result = acc.finalize();
+ *   // → [{ function: { name: 'get_weather', arguments: { city: 'Tokyo', unit: 'celsius' } } }]
+ *   ```
+ */
+declare class ToolCallAccumulator {
+    private readonly entries;
+    /**
+     * Process a chunk's `tool_calls` array. Entries that match an
+     * existing accumulated entry (by id or array position) are merged;
+     * new entries are appended.
+     *
+     * Returns the current accumulated state (a shallow copy — entries
+     * themselves are NOT deep-cloned, so callers that mutate
+     * `function.arguments` on a returned entry will mutate the
+     * accumulator's internal state. Use {@link snapshot} for an
+     * explicitly read-only view, or deep-clone the result if you need
+     * full isolation).
+     */
+    process(toolCalls: readonly ToolCall[] | undefined): readonly ToolCall[];
+    /**
+     * Returns the final accumulated tool calls. Identical to calling
+     * `process(undefined)` — included for ergonomics so callers can
+     * express "I'm done, give me the result" without a no-op call.
+     *
+     * The returned array is a shallow copy; entries themselves are
+     * the same object references the accumulator holds internally.
+     */
+    finalize(): readonly ToolCall[];
+    /**
+     * Returns the current accumulated state without modifying the
+     * accumulator. Useful for mid-stream inspection.
+     *
+     * The returned array is a shallow copy; mutating it (e.g.
+     * `result.push(...)`) does not affect the accumulator, but
+     * mutating an entry's `function.arguments` object DOES affect
+     * the accumulator's internal state because the entry reference
+     * is shared. Deep-clone the result if you need full isolation.
+     */
+    snapshot(): readonly ToolCall[];
+    /**
+     * Returns the number of accumulated tool calls so far.
+     */
+    get length(): number;
+}
+/**
+ * Convenience function: merge two `tool_calls` arrays using the
+ * default accumulator semantics, returning the merged array.
+ *
+ * Stateless equivalent of:
+ *
+ *   ```ts
+ *   const acc = new ToolCallAccumulator();
+ *   acc.process(earlier);
+ *   acc.process(later);
+ *   return acc.finalize();
+ *   ```
+ *
+ * Useful for one-off merges without instantiating an accumulator.
+ */
+declare function mergeToolCallArrays(earlier: readonly ToolCall[] | undefined, later: readonly ToolCall[] | undefined): readonly ToolCall[];
+
 /**
  * Converts MCP tools into Ollama-compatible tools.
  */
@@ -1844,15 +2530,131 @@ declare const GEN_AI_SYSTEM_OLLAMA = "ollama";
  * Cross-runtime helpers with no Node.js API dependency, so they stay safe to import from
  * the core client bundle (see ADR 0006 — Edge Runtime CI).
  */
+
 /**
  * Encodes an image to a base64 string, matching the wire format Ollama's `/api/chat` and
  * `/api/generate` `images` arrays expect.
  *
- * - A `string` is assumed to already be base64-encoded and is returned unchanged.
- * - A `Uint8Array` is base64-encoded using whichever universal primitive the runtime
- *   exposes: `Buffer` on Node.js, `btoa` on browsers/Edge runtimes. Chunked so it doesn't
- *   blow the engine's max call-stack/argument-count limits on large images.
+ * - A `string` is assumed to already be base64-encoded and is returned unchanged. For
+ *   data URIs, URLs, and local file paths use {@link resolveImageInput}, which this SDK's
+ *   request pipeline applies automatically (see {@link withEncodedImages}).
+ * - A `Uint8Array` (or Node `Buffer`) is base64-encoded using whichever universal primitive
+ *   the runtime exposes: `Buffer` on Node.js, `btoa` on browsers/Edge runtimes. Chunked so it
+ *   doesn't blow the engine's max call-stack/argument-count limits on large images.
+ */
+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
+ * 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.
+ *
+ * The estimator is deliberately simple and documented as approximate
+ * (±20–30% vs a real BPE tokenizer):
+ *
+ *   - CJK code points (Chinese/Japanese/Korean) count as ~1 token each —
+ *     modern tokenizers emit roughly one token per CJK character.
+ *   - Everything else estimates at ~4 characters per token, the classic
+ *     English GPT-style average.
+ *   - Each attached image adds a fixed {@link IMAGE_TOKEN_ESTIMATE} —
+ *     vision encoders consume a roughly predictable tile budget per image
+ *     (e.g. LLaVA-family encoders emit a few hundred tokens per image).
+ *
+ * It is used in three places:
+ *
+ *   1. `OllamaClient.chat()`/`generate()` pre-flight — logs a warning (or
+ *      throws, per `onContextOverflow`) when the estimate crosses
+ *      {@link DEFAULT_CONTEXT_WARNING_THRESHOLD} of the effective window.
+ *   2. The `defaultContextLength` client config — injects `num_ctx` when the
+ *      caller didn't set one, making the effective window explicit instead
+ *      of server-default guesswork.
+ *   3. `ConversationSession` — sessions grow monotonically, so they surface
+ *      cache and context stats per turn.
+ */
+
+/**
+ * Fraction of the effective context window at which a pre-flight warning
+ * fires. 0.9 = warn when the estimated prompt reaches 90% of `num_ctx`.
+ * Above this, the response has little room left and the next turn's history
+ * will almost certainly overflow.
+ */
+declare const DEFAULT_CONTEXT_WARNING_THRESHOLD = 0.9;
+/**
+ * Rough token budget consumed per attached image. Vision encoders emit a few
+ * hundred embedding tokens per image tile; 300 sits between LLaVA-1.5's ~258
+ * and qwen-vl's higher tile counts. This is an estimate for warning purposes
+ * only — it never gates a request on its own unless images push the total
+ * past the threshold.
+ */
+declare const IMAGE_TOKEN_ESTIMATE = 300;
+/**
+ * Heuristic token estimate for a single text string: ~1 token per CJK
+ * character + ~1 token per 4 non-CJK characters. Approximate by design —
+ * accurate enough to warn against silent truncation without shipping a
+ * model-specific tokenizer.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Estimated prompt tokens for a `/api/chat` request: every message plus
+ * tool-schema overhead (each tool definition's JSON schema serializes into
+ * the prompt on Ollama's side).
+ */
+declare function estimateChatRequestTokens(req: ChatRequestOptions): number;
+/** Estimated prompt tokens for a `/api/generate` request (prompt + system + images). */
+declare function estimateGenerateRequestTokens(req: GenerateRequestOptions): number;
+/** Where the context window used by a pre-flight check came from. */
+type ContextWindowSource = 
+/** Explicit `options.num_ctx` on the request — exact, server-enforced. */
+'request'
+/** Client `defaultContextLength` config — injected as `num_ctx` by the pipeline. */
+ | 'client-default'
+/** Neither set; Ollama's server default applies (2048–4096, model-dependent). */
+ | 'server-fallback';
+/** What the pre-flight check concluded about one request. */
+interface ContextCheck {
+    /** Estimated prompt tokens (heuristic — see {@link estimateTokens}). */
+    readonly estimatedPromptTokens: number;
+    /** The context window the estimate was compared against. */
+    readonly effectiveContextLength: number;
+    /** Where that window came from. */
+    readonly windowSource: ContextWindowSource;
+    /** True when the estimate crossed the warning threshold of the effective window. */
+    readonly exceedsThreshold: boolean;
+}
+interface ContextCheckOptions {
+    /** Client `defaultContextLength`, applied when the request doesn't set `num_ctx`. */
+    readonly defaultContextLength?: number | undefined;
+    /** Warning threshold; defaults to {@link DEFAULT_CONTEXT_WARNING_THRESHOLD}. */
+    readonly threshold?: number | undefined;
+}
+/**
+ * Runs the pre-flight context check for a chat request. Pure — callers decide
+ * what to do with the result (log, throw, ignore).
+ */
+declare function checkChatContext(req: ChatRequestOptions, options?: ContextCheckOptions): ContextCheck;
+/**
+ * Runs the pre-flight context check for a generate request. Pure — callers
+ * decide what to do with the result (log, throw, ignore).
+ */
+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.
+ */
+declare const OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
+/**
+ * Builds the human-readable warning text for a failed pre-flight check.
+ * Exported for reuse by `ConversationSession` and for tests.
  */
-declare function encodeImage(image: Uint8Array | string): Promise<string>;
+declare function contextWarningMessage(check: ContextCheck, kind: 'chat' | 'generate'): string;
 
-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, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnthropicCacheControl, AnthropicCompatClient, type AnthropicContentBlock, type AnthropicImageContentBlock, type AnthropicMessage, type AnthropicMessageStreamEvent, type AnthropicMessagesRequest, type AnthropicMessagesResponse, AnthropicMessagesStream, type AnthropicMetadata, type AnthropicOutputConfig, type AnthropicRedactedThinkingContentBlock, type AnthropicSystem, type AnthropicSystemTextBlock, type AnthropicTextContentBlock, type AnthropicThinkingConfig, type AnthropicThinkingContentBlock, type AnthropicTool, type AnthropicToolChoice, type AnthropicToolResultContentBlock, type AnthropicToolUseContentBlock, type AnthropicUnknownStreamEvent, AnyTool, type BackoffOptions, ChatRequestOptions, ChatResponse, ChatStreamResult, CopyRequestOptions, CreateRequestOptions, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_FAILOVER_CODES, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type DefineToolOptions, DeleteRequestOptions, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, HttpClient, type LoadMcpToolsOptions, Logger, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, OLLAMA_CLOUD_BASE_URL, type OllamaAnthropicContentBlock, type OllamaAnthropicMessage, type OllamaAnthropicMessagesRequest, type OllamaAnthropicSystem, type OllamaAnthropicSystemTextBlock, type OllamaAnthropicTextContentBlock, type OllamaAnthropicThinkingConfig, type OllamaAnthropicTool, type OllamaAnthropicToolResultContentBlock, OllamaClient, type OllamaClientConfig, OllamaClientError, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, type OllamaOpenAIChatCompletionRequest, type OllamaOpenAICompletionRequest, type OllamaOpenAIEmbeddingRequest, type OllamaOpenAIReasoningEffort, type OllamaOpenAIResponsesRequest, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionChunkChoice, type OpenAIChatCompletionDelta, type OpenAIChatCompletionRequest, type OpenAIChatCompletionResponse, OpenAIChatCompletionStream, OpenAICompatClient, type OpenAICompletionChoice, type OpenAICompletionChunk, type OpenAICompletionRequest, type OpenAICompletionResponse, OpenAICompletionStream, type OpenAIContentPart, type OpenAIEmbeddingInput, type OpenAIEmbeddingItem, type OpenAIEmbeddingRequest, type OpenAIEmbeddingResponse, type OpenAIFunctionDefinition, type OpenAIImageUrlContentPart, type OpenAIListModelsResponse, type OpenAIMessage, type OpenAIModelItem, type OpenAIReasoningEffort, type OpenAIResponseFormat, type OpenAIResponsesCompletedEvent, type OpenAIResponsesContentPartAddedEvent, type OpenAIResponsesContentPartDoneEvent, type OpenAIResponsesCreatedEvent, type OpenAIResponsesError, type OpenAIResponsesEventBase, type OpenAIResponsesFailedEvent, type OpenAIResponsesFunctionCallArgumentsDeltaEvent, type OpenAIResponsesFunctionCallArgumentsDoneEvent, type OpenAIResponsesInProgressEvent, type OpenAIResponsesIncompleteDetails, type OpenAIResponsesIncompleteEvent, type OpenAIResponsesOutputContent, type OpenAIResponsesOutputFunctionCall, type OpenAIResponsesOutputItem, type OpenAIResponsesOutputItemAddedEvent, type OpenAIResponsesOutputItemDoneEvent, type OpenAIResponsesOutputMessage, type OpenAIResponsesOutputReasoning, type OpenAIResponsesOutputRefusal, type OpenAIResponsesOutputTextContent, type OpenAIResponsesOutputTextDeltaEvent, type OpenAIResponsesOutputTextDoneEvent, type OpenAIResponsesQueuedEvent, type OpenAIResponsesReasoningSummaryPartAddedEvent, type OpenAIResponsesReasoningSummaryPartDoneEvent, type OpenAIResponsesReasoningSummaryTextDeltaEvent, type OpenAIResponsesReasoningSummaryTextDoneEvent, type OpenAIResponsesReasoningTextDeltaEvent, type OpenAIResponsesReasoningTextDoneEvent, type OpenAIResponsesRefusalDeltaEvent, type OpenAIResponsesRefusalDoneEvent, type OpenAIResponsesRequest, type OpenAIResponsesResponse, type OpenAIResponsesStatus, OpenAIResponsesStream, OpenAIResponsesStreamError, type OpenAIResponsesStreamEvent, type OpenAIResponsesUsage, type OpenAIStreamOptions, type OpenAITextContentPart, type OpenAITool, type OpenAIToolCall, type OpenAIToolCallDelta, type OpenAIUsage, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RawUsageSource, RequestLifecycleHook, type RequestRunner, type RetryConfig, type RuntimeMode, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, SseEvent, StatusResponse, type SupportedSchema, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolDefinition, ToolExecutionResult, ToolHandler, ToolRegistry, VersionResponse, WebFetchRequestOptions, WebFetchResponse, WebSearchRequestOptions, WebSearchResponse, addSpanEvent, calculateBackoff, checkEndpointHealth, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, encodeImage, inferRuntimeMode, listAllMcpTools, listAvailableModels, loadMcpTools, normalizeChatStream, normalizeGenerateStream, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveCredentialEndpoints, 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, 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 ContextCheck, type ContextCheckOptions, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, CreateRequestOptions, type CumulativeCacheStats, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, type DefineToolOptions, DeleteRequestOptions, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, 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, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, 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 ParallelToolCallBehavior, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, 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, WebFetchRequestOptions, WebFetchResponse, WebSearchRequestOptions, WebSearchResponse, addSpanEvent, calculateBackoff, checkChatContext, checkEndpointHealth, checkGenerateContext, contextWarningMessage, createDecision, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateSystemOneRequestBytes, estimateTokens, fetchWithBackoff, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveCredentialEndpoints, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };