@nemesis-oss/ollama-sdk 1.8.0 → 1.9.0

package/dist/index.d.ts

@@ -1,16 +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, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-C6UYtBRB.js';
-export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NOOP_LOGGER, r as NextFunction, s as OllamaAbortError, t as OllamaAgentMaxIterationsError, u as OllamaAgentMaxToolCallsError, v as OllamaAuthError, w as OllamaClientError, x as OllamaClientErrorOptions, y as OllamaErrorRequestContext, z as OllamaErrorResponseContext, J as OllamaGenericClientError, K as OllamaIncompatibleModelError, Q as OllamaMcpError, U as OllamaModelRoutingError, V as OllamaNetworkError, W as OllamaNotFoundError, X as OllamaQuotaExceededError, Y as OllamaRateLimitError, Z as OllamaRequestTooLargeError, _ as OllamaRequestValidationError, $ as OllamaResponseValidationError, a0 as OllamaServerError, a1 as OllamaServerVersionUnknownError, a2 as OllamaSkillInvalidError, a3 as OllamaSkillNotFoundError, a4 as OllamaTimeoutError, a5 as OllamaToolTimeoutError, a6 as OllamaToolValidationError, a7 as OllamaUnsupportedCapabilityError, a8 as RequestContext, a9 as RequestLifecycleEvent, aa as ResponseContext, ab as SseEvent, ac as ThinkingEvent, ad as TokenEvent, ae as ToolCallEvent, af as composeMiddleware, ag as createConsoleLogger, ah as extractUsage, ai as mapError, aj as parseSseStream } from './runtime-C6UYtBRB.js';
-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.js';
-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.js';
+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-C3rfpkZw.js';
+export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NOOP_LOGGER, r as NextFunction, s as OllamaAbortError, t as OllamaAgentMaxIterationsError, u as OllamaAgentMaxToolCallsError, v as 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-C3rfpkZw.js';
+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.js';
+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.js';
 import { z } from 'zod';
-import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-B_UXplNF.js';
-export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as 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-B_UXplNF.js';
-import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-DLStUfaF.js';
-export { d as AppliedSkillResult, e as ApplySkillOptions, P as ParsedFrontmatter, S as Skill, f as SkillFrontmatter, g as SkillSummary, h as ToolExecutionContext, i as ToolExecutionFailure, j as ToolExecutionSuccess, k as ToolRegistryOptions, l as applySkill, p as parseFrontmatter } from './compose-DLStUfaF.js';
+import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-5oYIRS6D.js';
+export { y as AnthropicCacheControl, z as AnthropicContentBlock, B as AnthropicImageContentBlock, C as AnthropicMessage, n as AnthropicMessageStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, D as AnthropicMessagesStream, E as AnthropicMetadata, F as AnthropicOutputConfig, G as AnthropicRedactedThinkingContentBlock, H as AnthropicSystem, I as AnthropicSystemTextBlock, J as AnthropicTextContentBlock, K as AnthropicThinkingConfig, L as AnthropicThinkingContentBlock, M as AnthropicTool, P as AnthropicToolChoice, Q as AnthropicToolResultContentBlock, T as AnthropicToolUseContentBlock, U as AnthropicUnknownStreamEvent, V as OllamaAnthropicContentBlock, W as OllamaAnthropicMessage, X as OllamaAnthropicMessagesRequest, Y as OllamaAnthropicSystem, Z as OllamaAnthropicSystemTextBlock, _ as OllamaAnthropicTextContentBlock, $ as OllamaAnthropicThinkingConfig, a0 as OllamaAnthropicTool, a1 as OllamaAnthropicToolResultContentBlock, a2 as OllamaOpenAIChatCompletionRequest, a3 as 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-5oYIRS6D.js';
+import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-DCVYMvOL.js';
+export { d as AppliedSkillResult, e as ApplySkillOptions, P as ParsedFrontmatter, S as Skill, f as SkillFrontmatter, g as SkillSummary, h as ToolExecutionContext, i as ToolExecutionFailure, j as ToolExecutionSuccess, k as ToolRegistryOptions, l as applySkill, p as parseFrontmatter } from './compose-DCVYMvOL.js';
 import { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.js';
 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.js';
 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.
  */
@@ -291,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;
 }
@@ -314,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[];
@@ -338,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>;
@@ -375,6 +563,13 @@ declare class OllamaStream<TChunk, TFinal> implements AsyncIterable<OllamaStream
  * 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
@@ -413,8 +608,377 @@ 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>;
+}
+
+/**
+ * Ergonomic OpenAI Responses API bridge — `client.responses.create()`.
+ *
+ * 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.
+ */
+
+/** Flat tool definition, matching the `openai` npm SDK's `tools[]` shape. */
+interface ResponsesToolDefinition {
+    readonly name: string;
+    readonly description?: string | undefined;
+    readonly parameters?: ToolParameters | undefined;
+}
+/** Reasoning effort levels Ollama's `/v1/responses` accepts under `reasoning.effort`. */
+type ResponsesReasoningEffort = 'low' | 'medium' | 'high';
+/**
+ * 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 ResponsesCreateRequest extends RequestCancellationOptions {
+    readonly model: string;
+    /** 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 ResponsesToolDefinition[] | undefined;
+    readonly temperature?: number | undefined;
+    readonly top_p?: number | undefined;
+    readonly max_output_tokens?: number | 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;
+}
+/** Token usage in OpenAI Responses naming. */
+interface ResponsesUsage {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly total_tokens: number;
+}
+/**
+ * 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 model: string;
+    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;
+} | {
+    readonly type: 'thinking_delta';
+    readonly delta: string;
+} | {
+    readonly type: 'done';
+    readonly response: ResponsesCreateResponse;
+};
+/**
+ * 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>;
+}
+
+/**
+ * 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.
+ */
+
+/** 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;
+}
+/** 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;
+}
+/**
+ * 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;
 }
 
 /**
@@ -453,6 +1017,28 @@ declare class ModelsClient {
  * 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
@@ -513,6 +1099,23 @@ type SystemOneAnswers<Q extends SystemOneQuestions = SystemOneQuestions> = {
  *
  * 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;
@@ -526,6 +1129,27 @@ interface SystemOneResponse<Q extends SystemOneQuestions = SystemOneQuestions> e
     readonly answers: SystemOneAnswers<Q>;
     readonly usage: SystemOneUsage;
 }
+/**
+ * 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.
@@ -795,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;
     /**
@@ -851,6 +1481,48 @@ declare class OllamaClient {
      */
     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
@@ -930,6 +1602,18 @@ 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
@@ -977,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
@@ -1003,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.
  */
@@ -1013,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>;
 
@@ -1157,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.
  */
@@ -1348,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 AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, CopyRequestOptions, CreateRequestOptions, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_FAILOVER_CODES, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, 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, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, type RankResult, RawUsageSource, RequestLifecycleHook, RequestRunner, type RetryConfig, type RuntimeMode, type ScoreDecision, 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, ToolDefinition, ToolExecutionResult, ToolHandler, ToolRegistry, VersionResponse, WebFetchRequestOptions, WebFetchResponse, WebSearchRequestOptions, WebSearchResponse, addSpanEvent, calculateBackoff, checkEndpointHealth, createDecision, 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 };