@nemesis-oss/ollama-sdk 1.10.0 → 1.12.0

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-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-BsdBbuOv.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-BsdBbuOv.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-BtQexFpT.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-BtQexFpT.cjs';
+import { T as ThinkingMetadata, M as ModelResponse, R as RequestCancellationOptions, S as ShowRequestOptions, a as ShowResponse, P as PullRequestOptions, b as ProgressResponse, c as PushRequestOptions, C as CreateRequestOptions, D as DeleteRequestOptions, d as StatusResponse, e as CopyRequestOptions, f as PsResponse, V as VersionResponse, g as ToolParameters, h as ThinkValue, i as ToolCall, j as ChatRequestOptions, k as ModelOptions, l as ToolDefinition, F as FormatOption, m as ChatResponse, n as Message, G as GenerateRequestOptions, o as GenerateResponse, E as EmbedRequestOptions, p as EmbedResponse, q as EmbeddingsRequestOptions, r as EmbeddingsResponse, W as WebSearchRequestOptions, s as WebSearchResponse, t as WebFetchRequestOptions, u as WebFetchResponse, U as UsageRequestOptions, B as BalanceRequestOptions, v as PingResult, w as VisionInput } from './types-B57ZZfp3.cjs';
+export { L as ListResponse, x as Logprob, y as LogprobToken, z as ModelDetails, A as Role, H as ToolCallFunction, I as ToolFunctionDefinition, J as ToolProperty, K as UsageRange, N as UsageScope, O as WebSearchResult, Q as imageStringNeedsResolution, X as resolveImageInput } from './types-B57ZZfp3.cjs';
+import { H as HttpClient, F as FetchLike, M as Middleware, L as Logger, R as RequestLifecycleHook, c as OllamaStreamEvent, A as AbortableAsyncIterable, d as OllamaStreamEventType, P as ProgressStreamResult, B as BinaryBody, O as OllamaRuntime, C as ChatStreamResult, G as GenerateStreamResult, e as RawUsageSource, T as TokenUsage } from './runtime-DmI1cOEq.cjs';
+export { D as DoneEvent, E as ErrorEvent, f as HttpBody, g as HttpClientOptions, h as HttpRequestOptions, i as LifecycleErrorEvent, j as LifecycleRetryEvent, k as LifecycleStartEvent, l as LifecycleSuccessEvent, m as LogFn, n as MessageEvent, o as MiddlewareContext, N as NANOS_PER_MS, p as NANOS_PER_SECOND, q as NOOP_LOGGER, r as NextFunction, s as OllamaAbortError, t as OllamaAgentMaxIterationsError, u as OllamaAgentMaxToolCallsError, v as OllamaAgentToolLoopError, w as OllamaAuthError, x as OllamaBadGatewayError, y as OllamaClientError, z as OllamaClientErrorOptions, J as OllamaErrorRequestContext, K as OllamaErrorResponseContext, Q as OllamaGenericClientError, U as OllamaIncompatibleModelError, V as OllamaMcpError, W as OllamaModelRoutingError, X as OllamaNetworkError, Y as OllamaNotFoundError, Z as OllamaOverloadedError, _ as OllamaQuotaExceededError, $ as OllamaRateLimitError, a0 as OllamaRequestTooLargeError, a1 as OllamaRequestValidationError, a2 as OllamaResponseValidationError, a3 as OllamaServerError, a4 as OllamaServerVersionUnknownError, a5 as OllamaSkillInvalidError, a6 as OllamaSkillNotFoundError, a7 as OllamaStreamError, a8 as OllamaTimeoutError, a9 as OllamaToolTimeoutError, aa as OllamaToolValidationError, ab as OllamaUnsupportedCapabilityError, ac as RequestContext, ad as RequestLifecycleEvent, ae as ResponseContext, af as SseEvent, ag as ThinkingEvent, ah as TokenEvent, ai as ToolCallEvent, aj as composeMiddleware, ak as createConsoleLogger, al as extractUsage, am as mapError, an as parseSseStream } from './runtime-DmI1cOEq.cjs';
 import { z } from 'zod';
-import { R as RequestRunner, S as SystemOneChoiceAnswer, o as SystemOneNoulAnswer, p as SystemOneScoreAnswer, q as SystemOneChoiceQuestion, r as SystemOneNoulQuestion, s as SystemOneScoreQuestion, t as SystemOneRequest$1, u as SystemOneResponse$1, v as SystemOneContent, N as NativeApi, w as OpenAICompatClient, x as AnthropicCompatClient } from './anthropic-DuE8M6Tz.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-DuE8M6Tz.cjs';
-import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-lt-Qz3lI.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-lt-Qz3lI.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-Did0lQxP.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-Did0lQxP.cjs';
+import { T as ToolHandler, a as Tool, A as AnyTool, b as ToolRegistry, c as ToolExecutionResult } from './compose-DhvoUrWa.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-DhvoUrWa.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';
@@ -122,6 +122,220 @@ interface UsageResponse {
     readonly buckets: readonly UsageBucket[];
 }
 
+/**
+ * Model capability detection and runtime environment inference.
+ */
+
+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[];
+    readonly supportsTools: boolean;
+    readonly supportsVision: boolean;
+    readonly supportsEmbedding: boolean;
+    readonly supportsCompletion: boolean;
+    readonly supportsThinking: boolean;
+    /** Model-defined thinking values and default, when /api/show reports them. */
+    readonly thinking?: ThinkingMetadata | undefined;
+    readonly supportsStreaming: true;
+    /** Maximum model context length reported by /api/show model_info, when available. */
+    readonly contextLength?: number | undefined;
+    /**
+     * Best-effort inference, not a guarantee: Ollama's `/api/show` does not report structured
+     * output support as a queryable capability, so this is inferred from {@link inferRuntimeMode}
+     * — `false` for `cloud`, since Ollama Cloud does not currently support structured outputs;
+     * `true` for `local`/`unknown`. A locally-hosted model that genuinely can't follow a JSON
+     * schema will still report `true` here; the request itself is the only reliable way to find
+     * out. `OllamaClient.chat`/`generate` apply this same inference as a fail-fast pre-flight
+     * guard whenever `format` is set, throwing `OllamaUnsupportedCapabilityError` rather than
+     * 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;
+/**
+ * Scans `/api/show`'s `model_info` for the model's **native** context length
+ * (keys are architecture-prefixed: `llama.context_length`,
+ * `gemma4.context_length`, …). Also re-exported by `src/context-discovery.ts`
+ * as `extractNativeContextLength` for the context-window discovery flow.
+ */
+declare function extractContextLength(modelInfo?: Record<string, unknown>): number | undefined;
+declare function detectModelCapabilities(http: HttpClient, model: string, signal?: AbortSignal): Promise<ModelCapabilities>;
+declare function listAvailableModels(http: HttpClient): Promise<ModelResponse[]>;
+
+/**
+ * Dynamic context-window discovery.
+ *
+ * Guessing context windows ("it's probably 2048… or 4096?") is how silent
+ * truncation happens. Ollama advertises the real numbers in two places, and
+ * they answer *different questions*:
+ *
+ *   - **`GET /api/ps`** reports `context_length` for every currently-running
+ *     model — the window the runner has **actually allocated**. This is the
+ *     exact, server-enforced number: it already reflects the model's Modelfile
+ *     `num_ctx` default (if any) and the memory the runner was able to claim.
+ *     Only meaningful while the model is loaded.
+ *   - **`POST /api/show`** exposes two deeper signals in its response:
+ *     - `model_info["<architecture>.context_length"]` — the model's **native**
+ *       maximum from its GGUF metadata (e.g. `gemma4.context_length: 131072`).
+ *       This is the ceiling you could raise `num_ctx` to, not the window you
+ *       have. The official API examples show a model whose native max is
+ *       131072 while its running instance allocated 4096 — a 32× gap.
+ *     - `parameters` — the Modelfile's serialized option list; a
+ *       `num_ctx <n>` line (when the model's author set one) is the default
+ *       window the runner will allocate for this model.
+ *
+ * `OllamaClient.models.getContextLength()` consults them in precedence order
+ * (see {@link resolveContextLength}) and returns every signal it found, so
+ * callers can both act on the effective window *now* and know how much
+ * headroom exists for raising it.
+ */
+
+/** Request shape for {@link ModelsClient.getContextLength}. */
+interface ContextDiscoveryRequestOptions extends RequestCancellationOptions {
+    /** Model to introspect (tag optional — `"llama3.1"` matches `"llama3.1:latest"`). */
+    readonly model: string;
+    /**
+     * Skip the `GET /api/ps` lookup — e.g. on cloud endpoints where the local
+     * running-models listing isn't meaningful, or when the extra round-trip
+     * isn't wanted. Discovery then falls back to `/api/show` signals only.
+     */
+    readonly skipRunningCheck?: boolean | undefined;
+}
+/** Where a discovered context window came from, in precedence order. */
+type ContextLengthSource = 
+/** `GET /api/ps` — window actually allocated by the running instance (exact). */
+'running'
+/** `POST /api/show` `parameters` — Modelfile-authored `num_ctx` default. */
+ | 'parameters'
+/** `POST /api/show` `model_info["*.context_length"]` — native GGUF maximum. */
+ | 'model-info'
+/** Nothing discoverable — Ollama's conservative unset-`num_ctx` default (2048). */
+ | 'fallback';
+/** Result of {@link ModelsClient.getContextLength}. */
+interface DiscoveredContextLength {
+    /**
+     * The effective context window to program against, resolved by precedence:
+     * `running` (exact, when loaded) → `parameters` (Modelfile default) →
+     * `model-info` (native max) → `2048` fallback.
+     */
+    readonly contextLength: number;
+    /** Which source produced {@link contextLength}. */
+    readonly source: ContextLengthSource;
+    /** Window allocated by the running instance, when the model is loaded and reports it. */
+    readonly runningContextLength?: number | undefined;
+    /** Modelfile `num_ctx` default from `/api/show`'s `parameters` string, when set. */
+    readonly parameterContextLength?: number | undefined;
+    /** Native GGUF maximum from `model_info["*.context_length"]`, when reported. */
+    readonly nativeContextLength?: number | undefined;
+}
+/**
+ * Parses `num_ctx <n>` out of `/api/show`'s `parameters` string.
+ *
+ * The string is the Modelfile's serialized option list — one `name value`
+ * pair per line, value separated by whitespace padding, e.g.
+ * `"num_stop 8192\nnum_ctx 4096"`. Returns `undefined` when no positive
+ * integer `num_ctx` line is present.
+ */
+declare function extractParameterNumCtx(parameters?: string | undefined): number | undefined;
+/**
+ * Whether `model` is currently resident (loaded in VRAM) per a `GET /api/ps`
+ * response — exact or tag-less-prefix match, same resolution rules as Ollama
+ * itself applies to model names. See {@link matchesModelReference}.
+ */
+declare function isModelResident(psModels: readonly {
+    readonly name?: string | undefined;
+    readonly model?: string | undefined;
+}[], model: string): boolean;
+/**
+ * Finds the context window Ollama actually allocated for `model`, from a
+ * `GET /api/ps` response. Matching mirrors Ollama's own model resolution:
+ * exact match on the entry's `name`/`model`, or — when `model` carries no
+ * tag — any entry whose name starts with `<model>:`.
+ *
+ * Returns `undefined` when the model isn't loaded or the running entry
+ * doesn't report `context_length` (older server versions).
+ */
+declare function findRunningModelContextLength(psModels: readonly ModelResponse[], model: string): number | undefined;
+/** Internal inputs to {@link resolveContextLength}; each signal independently optional. */
+interface ContextLengthSignals {
+    readonly running?: number | undefined;
+    readonly parameter?: number | undefined;
+    readonly native?: number | undefined;
+}
+/**
+ * Resolves the effective context window from whatever signals were
+ * discovered, by precedence:
+ *
+ *   1. **`running`** — the allocated window of the loaded instance. When the
+ *      model is in memory this is the ground truth; it already incorporates
+ *      any Modelfile `num_ctx` default.
+ *   2. **`parameter`** — the Modelfile's `num_ctx`, i.e. the window the
+ *      runner *will* allocate for this model on the next cold load.
+ *   3. **`native`** — the GGUF maximum. Only used when nothing tighter is
+ *      known: a fresh `num_ctx`-less load may allocate far less than native
+ *      (Ollama's conservative default), so native is a *ceiling*, not an
+ *      expectation.
+ *   4. **Fallback** — {@link OLLAMA_FALLBACK_CONTEXT_LENGTH} (2048), the
+ *      conservative server-side default, so the result is always actionable.
+ *
+ * Pure — used by `ModelsClient.getContextLength()` and exported for callers
+ * that already hold `/api/ps` / `/api/show` responses.
+ */
+declare function resolveContextLength(signals: ContextLengthSignals): DiscoveredContextLength;
+
 /**
  * Exponential backoff with full jitter calculation.
  */
@@ -152,9 +366,133 @@ declare const DEFAULT_RETRY_CONFIG: RetryConfig;
  */
 declare function withRetry<T>(operation: (attempt: number) => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
 
+/**
+ * Multi-host model-affinity routing — prefer the endpoint already holding the
+ * requested model in VRAM.
+ *
+ * Ollama daemons keep a bounded set of models resident (`OLLAMA_MAX_LOADED_MODELS`).
+ * With several interchangeable endpoints serving the same models, sending a request
+ * to a host that doesn't currently hold the model forces an unload/cold-load swap
+ * on that host — the thrashing `ModelAffinityScheduler` avoids for a *single*
+ * client's task queues. This router brings the same affinity to the *multi-host*
+ * request path: given the candidate endpoints `executeWithFailover` would try
+ * anyway, it reorders them so hosts whose `GET /api/ps` shows the requested model
+ * resident come first.
+ *
+ * Design constraints (see ADR 0028):
+ *
+ * - **Zero added request latency.** Reordering is synchronous and consults only
+ *   cached `/api/ps` snapshots. A request never waits for a probe: when a
+ *   snapshot is missing or stale, the request proceeds with the unchanged
+ *   candidate order and the refresh happens in the background, warming the cache
+ *   for subsequent requests.
+ * - **Race-free with `least-connections`.** The reorder runs entirely between the
+ *   registry's synchronous `candidates()`/`filterWithCapacity()` and the
+ *   endpoint's `acquire()` — no `await` in between — so the strategy's
+ *   no-two-calls-pick-the-same-idle-endpoint guarantee is untouched. Affinity
+ *   only reorders *within* the runnable set; priority tiers and per-strategy
+ *   ordering stay intact inside the resident/non-resident groups.
+ * - **Best-effort, never blocking, never failing a request.** A probe failure is
+ *   recorded with a short backoff (`failureRetryMs`) and never cached as data;
+ *   the affected endpoint is simply treated as unknown until a probe succeeds.
+ * - **Fresh-data-only decisions.** Only snapshots within `ttlMs` reorder
+ *   requests — `/api/ps` can change at any moment (evictions, other clients),
+ *   so stale data is treated as no data. Last-known snapshots are still exposed
+ *   via `status()` for observability.
+ */
+
+/**
+ * One `/api/ps` running-model entry, as the router consumes it — name/model only.
+ * Optional to match the generated `Ps` wire shape; hand-written `ModelResponse`
+ * values (required fields) are assignable as-is.
+ */
+interface AffinityRunningModel {
+    readonly name?: string | undefined;
+    readonly model?: string | undefined;
+}
+/**
+ * Options for dynamic model-affinity routing across endpoints. Configured under
+ * `OllamaClientConfig.endpointHealth.modelAffinity`; implemented by
+ * `OllamaClient`'s request path (`executeWithFailover`), which has HTTP access —
+ * the `EndpointRegistry` itself ignores this key.
+ */
+interface ModelAffinityRoutingOptions {
+    /**
+     * How long a `GET /api/ps` snapshot stays fresh enough to reorder requests
+     * (default 30_000ms). Mirrors `ModelAffinityScheduler`'s `psCacheTtlMs`.
+     */
+    readonly ttlMs?: number | undefined;
+    /**
+     * How long a failed `/api/ps` probe suppresses retries against that endpoint
+     * (default 5_000ms) — a dead host isn't probed on every request while it's
+     * down, and comes back automatically once it recovers. Failures are never
+     * cached as data.
+     */
+    readonly failureRetryMs?: number | undefined;
+}
+/** Introspection snapshot for one endpoint's affinity cache. */
+interface ModelAffinitySnapshot {
+    readonly endpointName: string;
+    readonly baseUrl: string;
+    /** Model names reported resident by the last successful probe (may be stale). */
+    readonly loadedModels: readonly string[];
+    /** When the last successful probe completed — `undefined` if it never succeeded. */
+    readonly fetchedAt: number | undefined;
+    /** Whether the snapshot is within `ttlMs` and therefore still drives reordering. */
+    readonly fresh: boolean;
+}
+/** Test seam: injectable clock — defaults to `Date.now`. */
+type NowFn = () => number;
+/**
+ * Cache-and-reorder engine for multi-host model affinity. See the module docs for
+ * the design constraints; `OllamaClient` constructs one (only when
+ * `endpointHealth.modelAffinity` is set) and calls {@link reorder} synchronously
+ * inside its request path.
+ */
+declare class ModelAffinityRouter {
+    private readonly fetchPs;
+    private readonly ttlMs;
+    private readonly failureRetryMs;
+    private readonly now;
+    private readonly cache;
+    private readonly failedAt;
+    private readonly inflight;
+    constructor(fetchPs: (endpoint: OllamaEndpoint) => Promise<readonly AffinityRunningModel[]>, options?: ModelAffinityRoutingOptions & {
+        readonly now?: NowFn;
+    });
+    /**
+     * Synchronously reorders `candidates` so endpoints whose fresh `/api/ps`
+     * snapshot shows `model` resident come first (relative order preserved within
+     * each group). Returns the input unchanged — and kicks a background refresh —
+     * when any candidate's snapshot is missing or stale: a wrong reorder is worse
+     * than no reorder, and the first request after a cache miss simply isn't
+     * reordered. No-op without a `model` or with fewer than two candidates.
+     */
+    reorder(candidates: readonly OllamaEndpoint[], model: string | undefined): readonly OllamaEndpoint[];
+    /**
+     * Forces a refresh of the affinity cache for the given endpoints (deduped with
+     * any in-flight refresh; bypasses the failure backoff, because this is an
+     * explicit caller request — `client.warmModelAffinity()`). Resolves once every
+     * probe has settled — successfully or not; individual failures never reject.
+     */
+    warm(endpoints: readonly OllamaEndpoint[]): Promise<void>;
+    /** Introspection snapshots for the given endpoints (defaults to cached ones). */
+    status(endpoints?: readonly OllamaEndpoint[]): readonly ModelAffinitySnapshot[];
+    /**
+     * Starts (or joins) a background refresh for `endpoint`, unless one is already
+     * in flight or the failure backoff suppresses it. Fire-and-forget: the promise
+     * is stored only for dedupe/warm-joins; callers never await it on the request
+     * path.
+     */
+    private kickRefresh;
+    /** Refreshes one endpoint's snapshot; never rejects (failures record a backoff). */
+    private refresh;
+}
+
 /**
  * Multi-endpoint registry with priority routing and circuit breaker failover.
  */
+
 interface OllamaEndpoint {
     readonly name: string;
     readonly baseUrl: string;
@@ -222,6 +560,18 @@ interface EndpointRegistryOptions {
      * any other in-flight request — it never blocks indefinitely on its own.
      */
     readonly maxConcurrentPerEndpoint?: number | undefined;
+    /**
+     * Dynamic model-affinity routing across endpoints: reorder each request's
+     * candidates so endpoints whose `GET /api/ps` shows the requested model already
+     * resident in VRAM are tried first — avoiding unload/cold-load swaps on
+     * `OLLAMA_MAX_LOADED_MODELS`-bounded daemons. Off unless set.
+     *
+     * Implemented by `OllamaClient`'s request path (`executeWithFailover` + a
+     * TTL-cached `ModelAffinityRouter`), not by this registry — the registry is a
+     * pure, HTTP-free data structure and simply ignores this key. See
+     * `src/providers/model-affinity-router.ts` and ADR 0028.
+     */
+    readonly modelAffinity?: ModelAffinityRoutingOptions | undefined;
 }
 declare class EndpointRegistry {
     private readonly endpoints;
@@ -445,92 +795,6 @@ interface EndpointHealthCheckResult {
 }
 declare function checkEndpointHealth(endpoint: OllamaEndpoint, fetchImpl?: FetchLike, timeoutMs?: number, middleware?: readonly Middleware[] | undefined, onLifecycleEvent?: RequestLifecycleHook | undefined): Promise<EndpointHealthCheckResult>;
 
-/**
- * Model capability detection and runtime environment inference.
- */
-
-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[];
-    readonly supportsTools: boolean;
-    readonly supportsVision: boolean;
-    readonly supportsEmbedding: boolean;
-    readonly supportsCompletion: boolean;
-    readonly supportsThinking: boolean;
-    /** Model-defined thinking values and default, when /api/show reports them. */
-    readonly thinking?: ThinkingMetadata | undefined;
-    readonly supportsStreaming: true;
-    /** Maximum model context length reported by /api/show model_info, when available. */
-    readonly contextLength?: number | undefined;
-    /**
-     * Best-effort inference, not a guarantee: Ollama's `/api/show` does not report structured
-     * output support as a queryable capability, so this is inferred from {@link inferRuntimeMode}
-     * — `false` for `cloud`, since Ollama Cloud does not currently support structured outputs;
-     * `true` for `local`/`unknown`. A locally-hosted model that genuinely can't follow a JSON
-     * schema will still report `true` here; the request itself is the only reliable way to find
-     * out. `OllamaClient.chat`/`generate` apply this same inference as a fail-fast pre-flight
-     * guard whenever `format` is set, throwing `OllamaUnsupportedCapabilityError` rather than
-     * 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>;
-declare function listAvailableModels(http: HttpClient): Promise<ModelResponse[]>;
-
 /**
  * Dual-mode (AsyncIterator and EventEmitter-like) stream wrapper.
  */
@@ -606,7 +870,39 @@ declare class ModelsClient {
     create(request: CreateRequestOptions): Promise<ProgressResponse | OllamaStream<ProgressResponse, ProgressStreamResult>>;
     delete(request: DeleteRequestOptions): Promise<StatusResponse>;
     copy(request: CopyRequestOptions): Promise<StatusResponse>;
-    ps(): Promise<PsResponse>;
+    ps(request?: RequestCancellationOptions): Promise<PsResponse>;
+    /**
+     * Discovers the model's real context window from the server — no more
+     * 2048/4096 guesswork. Consults, in precedence order:
+     *
+     *   1. `GET /api/ps` — the window the **running instance actually
+     *      allocated** (exact, reflects the Modelfile `num_ctx` default and
+     *      what fit in memory); skipped when the model isn't loaded, when
+     *      `skipRunningCheck` is set, or harmlessly on servers without the
+     *      field.
+     *   2. `POST /api/show` `parameters` — a Modelfile-authored
+     *      `num_ctx <n>` default, i.e. the window a cold load will allocate.
+     *   3. `POST /api/show` `model_info["<arch>.context_length"]` — the
+     *      model's **native GGUF maximum** (a ceiling to raise `num_ctx`
+     *      toward, not the allocated window).
+     *   4. Fallback — Ollama's conservative unset-`num_ctx` default (2048).
+     *
+     * The result carries every signal it found, so `nativeContextLength:
+     * 131072` vs `contextLength: 4096` (a 32× gap seen in the official API
+     * examples) is visible rather than guessed. Typical wiring:
+     *
+     * ```ts
+     * const { contextLength, source, nativeContextLength } =
+     *   await client.models.getContextLength({ model: 'gemma4' });
+     * // -> { contextLength: 4096, source: 'running', nativeContextLength: 131072 }
+     * ```
+     *
+     * Makes two server calls (`/api/ps` + `/api/show`) unless
+     * `skipRunningCheck` is set. A 404 from `/api/ps` (endpoint without the
+     * listing) is treated as "not running" and never fails the lookup;
+     * other transport errors propagate normally.
+     */
+    getContextLength(request: ContextDiscoveryRequestOptions): Promise<DiscoveredContextLength>;
     version(): Promise<VersionResponse>;
     /**
      * Immediately unloads `model` from VRAM/RAM by issuing an empty
@@ -904,6 +1200,147 @@ interface SessionTurn {
     /** The full underlying `/api/chat` response (usage, durations, thinking, …). */
     readonly response: ChatResponse;
 }
+/** Options for {@link compactConversationHistory} / {@link ConversationSession.compact}. */
+interface CompactionOptions {
+    /**
+     * Estimated-token budget the compacted history must fit within (including
+     * any retained system message and the 10%-style reply reservation below).
+     * Estimated with the same CJK-aware heuristic as the pre-flight checks
+     * (`estimateMessageTokens` — ±20–30%, message overhead + tool calls +
+     * `IMAGE_TOKEN_ESTIMATE` per image included).
+     */
+    readonly maxEstimatedTokens: number;
+    /**
+     * Tokens subtracted from the budget and reserved for the model's next
+     * reply (default `0` for the pure function; `session.compact()` defaults
+     * to ~10% of the window, mirroring the pre-flight warning threshold's
+     * headroom).
+     */
+    readonly reserveForReply?: number | undefined;
+    /**
+     * Trailing messages always retained, even when they don't fit the budget
+     * (default `2` — the latest user/assistant exchange). Guarantees a
+     * compacted conversation never loses its most recent context; an
+     * oversized tail is retained deliberately rather than truncated, because
+     * silent truncation is the server's failure mode, not one this SDK
+     * reproduces.
+     */
+    readonly minTailMessages?: number | undefined;
+}
+/**
+ * Sliding-window history compaction: keep the pinned system message(s) plus
+ * the most recent turns that fit `maxEstimatedTokens`, dropping the oldest
+ * turns in between.
+ *
+ * Deliberately **not** automatic anywhere in the SDK: compaction rewrites the
+ * prompt prefix, so the next request's KV-cache hit rate drops to zero and
+ * the whole retained suffix re-evaluates. That tradeoff (latency + recompute
+ * for a window that now fits) is sometimes exactly right — long-running
+ * agent threads that would otherwise silently lose their oldest turns — and
+ * sometimes catastrophic (a hot cache-friendly session that never actually
+ * overflows). `ConversationSession.cacheStats` makes the "session no longer
+ * fits" case visible; this function is the explicit, caller-initiated fix.
+ *
+ * Semantics:
+ *
+ *   - **Leading `system` messages are always retained** and count against
+ *     the budget (they consume context too).
+ *   - Non-system messages are walked newest → oldest; each is retained while
+ *     it fits the remaining budget, or while fewer than `minTailMessages`
+ *     have been retained.
+ *   - Mid-conversation `system`/`tool` messages are ordinary tailable
+ *     history (only the *leading* system block is pinned).
+ *   - Returns a new array; the input is never mutated. Message objects are
+ *     reused by reference (sessions freeze them; external arrays are copied
+ *     defensively by the caller if needed).
+ *
+ * ```ts
+ * const kept = compactConversationHistory(session.getMessages(), {
+ *   maxEstimatedTokens: window.contextLength,
+ *   reserveForReply: 512,
+ * });
+ * ```
+ */
+declare function compactConversationHistory(messages: readonly Message[], options: CompactionOptions): readonly Message[];
+/** Options for {@link sanitizeHistoryForNextTurn}; all fields optional. */
+interface HistorySanitizeOptions {
+    /**
+     * Messages — counted from the **end** of the array — whose `images` are
+     * preserved. Default `1`: only the final message keeps its image payload,
+     * which is the rolling one-image window long-running vision chats almost
+     * always want (sanitize after appending the newest turn, and every prior
+     * base64 payload is gone by the next request). `0` evicts images
+     * everywhere; negative values clamp to `0`.
+     */
+    readonly keepImagesOnLastMessages?: number | undefined;
+    /**
+     * Optional note appended to the `content` of each evicted message so the
+     * model can still tell an image used to be there — e.g.
+     * `"[image from an earlier turn removed to save context]"`. When omitted
+     * (default) the `images` field is dropped and the text is untouched,
+     * matching the wire behavior of never having sent the image at all.
+     */
+    readonly imagePlaceholder?: string | undefined;
+}
+/**
+ * Vision-history hygiene: returns a copy of `messages` with image payloads
+ * evicted from every message outside the trailing keep-window, conversation
+ * text fully preserved.
+ *
+ * Ollama's `/api/chat` is stateless — each request re-sends and re-bills the
+ * whole history, base64 images included (each one costing real context
+ * tokens via `IMAGE_TOKEN_ESTIMATE` in the pre-flight estimators). A
+ * consumer-managed `messages` array therefore re-uploads every image from
+ * every prior turn on every request, long after the model has already
+ * answered the question that needed them. This helper is the explicit fix:
+ *
+ * ```ts
+ * history.push({ role: 'user', content: 'What is in THIS photo?', images: [nextImage] });
+ * await client.chat({ model, messages: sanitizeHistoryForNextTurn(history) });
+ * ```
+ *
+ * Same philosophy as {@link compactConversationHistory}: caller-initiated,
+ * never automatic. Two deliberate tradeoffs, both documented in ADR 0027:
+ *
+ *   - **The model loses access to evicted images** — it keeps the
+ *     conversation text (and the optional `imagePlaceholder` note) but can
+ *     no longer "see" earlier pictures. That is the point: a bounded
+ *     payload in exchange for fading visual memory.
+ *   - **KV-prefix invalidation** — evicting rewrites the message at that
+ *     position, so the next turn's prompt prefix diverges and the cache
+ *     re-evaluates from that point. A hot cache-friendly session shouldn't
+ *     sanitize; a growing vision session should.
+ *
+ * Pure: the input array is never mutated, and messages that keep their
+ * images are reused by reference (identity-stable for the untouched ones,
+ * fresh copies only where eviction happened).
+ */
+declare function sanitizeHistoryForNextTurn(messages: readonly Message[], options?: HistorySanitizeOptions): readonly Message[];
+/** Options for {@link ConversationSession.compact}; all fields optional. */
+interface SessionCompactionOptions {
+    /**
+     * Token budget for the compacted history. Defaults to the session's own
+     * window: `options.num_ctx` from the session config, or Ollama's
+     * conservative 2048 fallback when unset — pair with
+     * `client.models.getContextLength()` to program against the real window.
+     */
+    readonly maxEstimatedTokens?: number | undefined;
+    /** Reply reservation; defaults to ~10% of the (derived) budget. */
+    readonly reserveForReply?: number | undefined;
+    /** Trailing messages always kept (default `2`). See {@link CompactionOptions}. */
+    readonly minTailMessages?: number | undefined;
+}
+/** What {@link ConversationSession.compact} did. */
+interface SessionCompactionResult {
+    /** Number of messages dropped from the front of the tailable history. */
+    readonly droppedMessages: number;
+    /** Estimated tokens of the whole history before compaction. */
+    readonly estimatedTokensBefore: number;
+    /** Estimated tokens of the retained history after compaction. */
+    readonly estimatedTokensAfter: number;
+    /** The budget that was applied (after the reply reservation). */
+    readonly effectiveBudget: number;
+}
 /** 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;
@@ -973,6 +1410,23 @@ declare class ConversationSession {
      * its frozen messages has no effect on the session.
      */
     getMessages(): readonly Message[];
+    /**
+     * Compacts the session's history in place: pinned system prompt plus the
+     * most recent turns that fit the budget, oldest tailable turns dropped.
+     *
+     * This is the explicit escape hatch for sessions that outgrew their
+     * window — `cacheStats.hitRate` collapsing toward zero while history grows
+     * is the usual symptom, and the pre-flight warnings on `chat()` fire once
+     * the prompt estimate crosses the threshold. After compaction the next
+     * turn's prompt prefix differs from everything before it, so the KV cache
+     * starts cold — visible as a one-turn `evaluatedTokens` spike in
+     * `cacheStats`. Cumulative cache tallies are deliberately **not** reset:
+     * they are observations, and the spike is part of the story.
+     *
+     * Returns the before/after estimates and the drop count. No-op (zero
+     * drops, equal before/after estimates) when the history already fits.
+     */
+    compact(options?: SessionCompactionOptions): SessionCompactionResult;
     /**
      * Clears the conversation back to its initial state (system prompt, zero
      * turns, zeroed cache statistics). The next turn starts with a cold cache
@@ -1558,6 +2012,16 @@ declare class OllamaClient {
      * (streams, via `executeWithFailover`'s `holdUntil` release path).
      */
     private readonly activeRequests;
+    /**
+     * Dynamic multi-host model-affinity routing, active only when
+     * `config.endpointHealth.modelAffinity` is set — see
+     * `src/providers/model-affinity-router.ts` and ADR 0028. `undefined` means
+     * the request path skips reordering entirely (zero overhead, and no `/api/ps`
+     * probes are ever issued).
+     */
+    private readonly modelAffinity;
+    /** Default timeout for one-off probe requests (`ping`, affinity `/api/ps` refreshes). */
+    private static readonly PROBE_TIMEOUT_MS;
     constructor(config?: OllamaClientConfig);
     get modelsClient(): ModelsClient;
     /**
@@ -1772,7 +2236,15 @@ declare class OllamaClient {
     readonly createModel: (r: CreateRequestOptions) => Promise<ProgressResponse | OllamaStream<ProgressResponse, ProgressStreamResult>>;
     readonly deleteModel: (req: DeleteRequestOptions) => Promise<StatusResponse>;
     readonly copyModel: (req: CopyRequestOptions) => Promise<StatusResponse>;
-    readonly ps: () => Promise<PsResponse>;
+    readonly ps: (request?: RequestCancellationOptions) => Promise<PsResponse>;
+    /**
+     * Discovers the model's real context window — the allocated window of the
+     * running instance (`/api/ps`), the Modelfile `num_ctx` default, and the
+     * native GGUF maximum (`/api/show` `model_info`), resolved by precedence.
+     * Convenience alias for {@link ModelsClient.getContextLength} — see that
+     * method for the full contract and the precedence order.
+     */
+    readonly getContextLength: (request: ContextDiscoveryRequestOptions) => Promise<DiscoveredContextLength>;
     readonly version: () => Promise<VersionResponse>;
     readonly createBlob: (digest: string, data: BinaryBody) => Promise<void>;
     readonly checkBlob: (digest: string) => Promise<boolean>;
@@ -1883,7 +2355,49 @@ declare class OllamaClient {
     capabilities(model: string, signal?: AbortSignal): Promise<ModelCapabilities>;
     runtimeMode(): RuntimeMode;
     healthCheck(): Promise<EndpointHealthCheckResult[]>;
+    /**
+     * Ultra-lightweight liveness probe against the client's current best
+     * endpoint: `HEAD /` — the root ping Ollama's documentation defines for
+     * load-balancer health checks (HTTP 200; the daemon answers `GET /` with the
+     * plain-text body "Ollama is running", which a HEAD request doesn't transfer).
+     *
+     * Deliberately a *single-endpoint, single-shot* probe — no failover to other
+     * candidates, no retry — so the answer reflects one concrete host, not "some
+     * endpoint eventually answered". To audit every configured endpoint, use
+     * {@link healthCheck} (which probes all of them, and also reports the server
+     * version at the cost of the heavier `GET /api/version` round trip).
+     *
+     * Resolves — never throws — with `{ healthy: false, error }` for connection
+     * failures and timeouts; only caller-initiated cancellation (`signal`/
+     * `destroy()`) rejects, mirroring how any other aborted request behaves.
+     */
+    ping(options?: RequestCancellationOptions): Promise<PingResult>;
+    /**
+     * Affinity-cache snapshots for every configured endpoint — which models each
+     * host held in VRAM at the last successful `/api/ps` probe, when that was, and
+     * whether it's still fresh. Empty when `endpointHealth.modelAffinity` isn't
+     * configured (no probes are ever issued, so there is nothing to report).
+     */
+    modelAffinityStatus(): readonly ModelAffinitySnapshot[];
+    /**
+     * Explicitly refreshes the model-affinity cache for every configured endpoint
+     * (deduped with any in-flight background refresh). No-op — resolves
+     * immediately — when `endpointHealth.modelAffinity` isn't configured. Use it
+     * to warm the cache at startup so the very first request already routes by
+     * residency instead of waiting for the self-warming first-round refresh.
+     */
+    warmModelAffinity(): Promise<void>;
     endpointStatus(): EndpointHealth[];
+    /**
+     * Fetches one endpoint's `GET /api/ps` running-model list for the affinity
+     * router. Bypasses `executeWithFailover` deliberately: probes must not
+     * reenter the routing machinery they inform, must not touch the registry's
+     * circuit-breaker/failure bookkeeping (a dead host's probe failing must not
+     * cool it down harder than its real traffic already does), and must not fail
+     * over to a different host (the answer is per-host by definition). Failures
+     * propagate to the router, which records a short backoff and retries later.
+     */
+    private fetchEndpointRunningModels;
     /**
      * Immediately aborts every in-flight request and active stream managed by
      * this client — the clean teardown path for short-lived processes, CLI
@@ -2607,6 +3121,22 @@ interface AgentConfig {
     readonly maxIterations?: number | undefined;
     /** Maximum total tool calls allowed during one agent run. */
     readonly maxToolCalls?: number | undefined;
+    /**
+     * Cycle detection: maximum executions of one *identical* tool call — same
+     * tool name and same arguments — during a single run. When the model would
+     * exceed this budget (the classic stuck-loop signature: re-emitting the
+     * same call without reacting to its results), the run fails fast with
+     * {@link OllamaAgentToolLoopError} instead of burning the remaining
+     * iterations on the same wasted call.
+     *
+     * Off by default (`undefined`), matching `maxToolCalls`: an explicit,
+     * caller-owned guardrail. Counting is per canonical signature, so
+     * argument key order never splits one repeated call into several
+     * "distinct" ones. Every call handed to the registry counts — failed,
+     * unregistered, and timed-out executions included, since re-calling a
+     * failing tool with unchanged arguments is exactly the loop this catches.
+     */
+    readonly maxRepeatedToolCalls?: number | undefined;
     readonly hooks?: AgentHooks | undefined;
     /** Validate tool support from /api/show before starting a tool-enabled run. Default: true. */
     readonly validateToolCapability?: boolean | undefined;
@@ -2642,6 +3172,18 @@ interface AgentChatClient {
         readonly message: Message;
     }>;
 }
+/**
+ * Canonical signature of a tool call for cycle detection: `name(args)` with
+ * recursively key-sorted arguments, so the same call re-emitted by a model
+ * in a different argument key order collapses to one signature instead of
+ * counting as two "distinct" calls.
+ *
+ * ```ts
+ * canonicalToolCallSignature({ function: { name: 'search', arguments: { q: 'x' } } })
+ * // 'search({"q":"x"})'
+ * ```
+ */
+declare function canonicalToolCallSignature(toolCall: ToolCall): string;
 /**
  * Runs a multi-turn `chat` + tool-execution loop until the model responds without
  * requesting further tool calls, or `maxIterations` is exceeded. Tool calls within a
@@ -2658,6 +3200,7 @@ declare class Agent {
     private readonly tools?;
     private readonly maxIterations;
     private readonly maxToolCalls?;
+    private readonly maxRepeatedToolCalls?;
     private readonly hooks?;
     private readonly validateToolCapability;
     private readonly toolContextSize;
@@ -2720,6 +3263,93 @@ declare const ATTR_OLLAMA_AGENT_MAX_ITERATIONS = "ollama.agent.max_iterations";
 declare const ATTR_OLLAMA_AGENT_ITERATION = "ollama.agent.iteration";
 declare const GEN_AI_SYSTEM_OLLAMA = "ollama";
 
+/**
+ * Standardized telemetry normalizer — raw nanosecond counters to derived metrics.
+ *
+ * Ollama reports every duration as an **integer in nanoseconds** on its generation
+ * responses (`total_duration`, `load_duration`, `prompt_eval_duration`,
+ * `eval_duration` — see the official "Usage" documentation), plus token counters
+ * (`prompt_eval_count`, `prompt_eval_cached_count`, `eval_count`). Consumers that
+ * want milliseconds, tokens/second, or a cache-hit ratio otherwise each reimplement
+ * the same division-and-rounding math — this module is that math, once, with the
+ * formulas the official docs spell out:
+ *
+ * - `tokensPerSecond` = `eval_count / (eval_duration / 1e9)` — generation throughput.
+ * - `promptTokensPerSecond` = `prompt_eval_count / (prompt_eval_duration / 1e9)` —
+ *   prompt ingestion (pre-fill) throughput.
+ * - `cacheHitRatio` = `prompt_eval_cached_count / (cached + evaluated)` — see the
+ *   note on {@link FormattedTelemetry.cacheHitRatio} for why the denominator is the
+ *   *sum*, not `prompt_eval_count` alone.
+ *
+ * Pure and dependency-free: {@link formatTelemetry} never fetches, never throws, and
+ * treats every missing counter as `0` — partial responses (stream final events,
+ * older servers without `prompt_eval_cached_count`) format cleanly instead of
+ * producing `NaN`/`Infinity`.
+ *
+ * The input is structural: any response object carrying these optional fields —
+ * `GenerateResponse`, `ChatResponse`, the final `GenerateStreamEvent`,
+ * `EmbedResponse` — can be passed directly, no picking/plucking required.
+ */
+/**
+ * The raw nanosecond/token counters Ollama attaches to generation responses. Every
+ * field is optional because servers report a subset: streaming final events may omit
+ * load counters, older builds predate `prompt_eval_cached_count`, and embeddings
+ * carry no `eval_count`. Accepts full response objects structurally.
+ */
+interface RawOllamaMetrics {
+    /** Total end-to-end request latency, nanoseconds. */
+    readonly total_duration?: number | undefined;
+    /** Model cold-load and weight-transfer time into VRAM, nanoseconds. */
+    readonly load_duration?: number | undefined;
+    /** Prompt tokens freshly evaluated this request (not served from the KV cache). */
+    readonly prompt_eval_count?: number | undefined;
+    /** Prompt tokens served from the KV prompt cache (prefix reuse). */
+    readonly prompt_eval_cached_count?: number | undefined;
+    /** Prompt ingestion / pre-fill processing time, nanoseconds. */
+    readonly prompt_eval_duration?: number | undefined;
+    /** Tokens generated (the response proper). */
+    readonly eval_count?: number | undefined;
+    /** Token generation time, nanoseconds. */
+    readonly eval_duration?: number | undefined;
+}
+/** The normalized, human-scale view of one response's {@link RawOllamaMetrics}. */
+interface FormattedTelemetry {
+    /** `total_duration` in milliseconds, 2 decimals. */
+    readonly totalLatencyMs: number;
+    /** `load_duration` in milliseconds, 2 decimals — 0 when the model was already resident. */
+    readonly modelLoadMs: number;
+    /** `prompt_eval_duration` in milliseconds, 2 decimals. */
+    readonly promptEvalMs: number;
+    /** `eval_duration` in milliseconds, 2 decimals. */
+    readonly generationMs: number;
+    /** `eval_count / eval_duration` in tokens/second, 1 decimal — 0 when either is absent. */
+    readonly tokensPerSecond: number;
+    /** `prompt_eval_count / prompt_eval_duration` in tokens/second, 1 decimal. */
+    readonly promptTokensPerSecond: number;
+    /**
+     * Share of prompt tokens served from the KV cache:
+     * `cached / (cached + evaluated)`, 3 decimals.
+     *
+     * The denominator is the **sum**, not `prompt_eval_count` alone, because Ollama
+     * reports `prompt_eval_count: 0` on a *full* cache hit — the same house semantics
+     * as `ConversationSession`'s `cacheStats.hitRate` (see `src/conversation.ts`). A
+     * `cached / prompt_eval_count` formula would report a perfect cache as `0`.
+     */
+    readonly cacheHitRatio: number;
+}
+/**
+ * Derives the standardized metrics summary from one response's raw nanosecond
+ * counters. Pure — never throws, never fetches; every missing counter reads as `0`.
+ *
+ * ```ts
+ * const res = await client.chat({ model: 'llama3.2', messages });
+ * const t = formatTelemetry(res);
+ * console.log(t.tokensPerSecond, 'tok/s |', t.totalLatencyMs, 'ms |',
+ *   `${Math.round(t.cacheHitRatio * 100)}% prompt cache hit`);
+ * ```
+ */
+declare function formatTelemetry(raw: RawOllamaMetrics): FormattedTelemetry;
+
 /**
  * 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).
@@ -2796,6 +3426,11 @@ declare const IMAGE_TOKEN_ESTIMATE = 300;
  * model-specific tokenizer.
  */
 declare function estimateTokens(text: string): number;
+/**
+ * Rough per-message framing overhead: role tags, chat-template delimiters.
+ */
+declare const MESSAGE_OVERHEAD_TOKENS = 4;
+declare function estimateMessageTokens(message: Message): number;
 /**
  * Estimated prompt tokens for a `/api/chat` request: every message plus
  * tool-schema overhead (each tool definition's JSON schema serializes into
@@ -2851,4 +3486,142 @@ declare const OLLAMA_FALLBACK_CONTEXT_LENGTH = 2048;
  */
 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, 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_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, type DefineToolOptions, DeleteRequestOptions, type EmbedBatchOptions, type EmbedBatchResult, 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 OversizedEmbedInput, 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, batchEmbed, calculateBackoff, checkChatContext, checkEndpointHealth, checkGenerateContext, contextWarningMessage, createDecision, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateSystemOneRequestBytes, estimateTokens, fetchWithBackoff, findOversizedEmbedInputs, 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 };
+/**
+ * Model-affinity scheduling: keep the daemon's working set small.
+ *
+ * Ollama's concurrency model (per the official FAQ):
+ *
+ *   - A model's KV cache scales by `OLLAMA_NUM_PARALLEL × context_length` —
+ *     parallel requests to the *same* loaded model are cheap (each gets its
+ *     own slot of the already-allocated cache).
+ *   - Requests for a *different* model queue until the first goes idle or is
+ *     evicted (`OLLAMA_MAX_LOADED_MODELS`, default 3× GPU count) — a swap is
+ *     an expensive unload/cold-load cycle: seconds of VRAM churn that a
+ *     concurrent multi-model workload pays again and again when it
+ *     interleaves models arbitrarily.
+ *   - Once `OLLAMA_MAX_QUEUE` (default 512) requests are waiting, new ones
+ *     are rejected outright with 503s.
+ *
+ * `ModelAffinityScheduler` is the client-side counterpart for workloads that
+ * juggle several models — extraction on a coder model, reasoning on a
+ * thinking model, embeddings for retrieval. It groups tasks into per-model
+ * serial queues and caps how many *distinct* models have work in flight
+ * (`concurrentModels`, default 1), preferring to deepen the currently-active
+ * model over starting the next one — the anti-thrashing order. Candidate
+ * lists let a task run on whichever of several interchangeable models is
+ * already loaded (`GET /api/ps`, cached with a TTL).
+ *
+ * It is a user-space primitive, deliberately not wired into `OllamaClient`'s
+ * request path: affinity decisions are workload policy, and the scheduler is
+ * the foundation the multi-instance routing work builds on. See ADR 0026.
+ */
+
+/**
+ * The minimal client surface the scheduler needs. `OllamaClient` satisfies it
+ * structurally; tests and custom setups can pass any compatible object.
+ */
+interface ModelAffinityClient {
+    readonly models: {
+        ps(): Promise<{
+            readonly models: ReadonlyArray<{
+                readonly name: string;
+            }>;
+        }>;
+    };
+}
+/** Options for {@link ModelAffinityScheduler}. */
+interface ModelAffinitySchedulerOptions {
+    /**
+     * Maximum number of *distinct* models with work in flight at once
+     * (default `1`). `1` is the anti-thrashing setting: one model stays hot
+     * until its queue drains, then the next loads. Raise it only when the
+     * host has VRAM for several concurrent models
+     * (`OLLAMA_MAX_LOADED_MODELS`).
+     */
+    readonly concurrentModels?: number | undefined;
+    /**
+     * Parallel tasks allowed per active model (default `1`). Raising this
+     * mirrors the server's own `OLLAMA_NUM_PARALLEL` — same-model parallelism
+     * reuses the loaded weights without swap cost.
+     */
+    readonly perModelConcurrency?: number | undefined;
+    /**
+     * How long a `GET /api/ps` result is reused when choosing among candidate
+     * models (default `30_000` ms). Only multi-candidate `run()` calls and
+     * `loadedModels()` consult the server; single-model tasks never do.
+     */
+    readonly psCacheTtlMs?: number | undefined;
+}
+/** Live scheduling state, from {@link ModelAffinityScheduler.stats}. */
+interface ModelAffinityStats {
+    /** Models with at least one task currently executing. */
+    readonly activeModels: readonly string[];
+    /** Tasks waiting in queues (not yet started). */
+    readonly queuedTasks: number;
+}
+/**
+ * Groups async work by model with load-aware dispatch.
+ *
+ * ```ts
+ * const scheduler = new ModelAffinityScheduler(client);
+ *
+ * // Serial queue per model; one model hot at a time (default):
+ * await scheduler.run('deepseek-r1', () => reason(client));
+ * await scheduler.run('qwen2.5:coder', () => extract(client));
+ *
+ * // Either-or: picks whichever candidate is already loaded (/api/ps):
+ * const summary = await scheduler.run(
+ *   ['qwen2.5:coder', 'qwen2.5:14b'],
+ *   (model) => extractWith(client, model),
+ * );
+ * ```
+ *
+ * Dispatch order is **affinity-sticky, not round-robin**: when a queued
+ * model is already active, its tasks start before a different model's (up to
+ * `perModelConcurrency`), because deepening the hot model avoids a swap.
+ * Tasks run in FIFO order within each model's queue. Task functions are the
+ * caller's own — the scheduler adds no retry, timeout, or failover, and a
+ * rejected task simply rejects its `run()` promise while its siblings
+ * proceed.
+ */
+declare class ModelAffinityScheduler {
+    private readonly client;
+    private readonly queues;
+    private readonly concurrentModels;
+    private readonly perModelConcurrency;
+    private readonly psCacheTtlMs;
+    private psCache;
+    private readonly drainWaiters;
+    constructor(client: ModelAffinityClient, options?: ModelAffinitySchedulerOptions);
+    /**
+     * Runs `task` on the scheduler, serialized per model. When `model` is a
+     * list of candidates, the already-loaded one is preferred (fresh
+     * `/api/ps` data subject to the TTL cache); with none loaded — or when the
+     * lookup fails — the first candidate runs. The chosen model is handed to
+     * the task.
+     */
+    run<T>(model: string | readonly string[], task: (model: string) => Promise<T>): Promise<T>;
+    /**
+     * Names of the models currently loaded, per `GET /api/ps`, cached for
+     * `psCacheTtlMs`. Degrades to an empty list when the server can't answer
+     * (never throws; candidate selection treats it as "nothing loaded").
+     */
+    loadedModels(): Promise<readonly string[]>;
+    /** Current scheduling state — active models and queued task count. */
+    get stats(): ModelAffinityStats;
+    /**
+     * Resolves once every queue is empty and no task is running. Does not
+     * abort anything — tasks are caller-owned; abort them via their own
+     * signals before disposing if needed.
+     */
+    dispose(): Promise<void>;
+    private chooseCandidate;
+    private refreshPsNames;
+    private pump;
+    private activeModelCount;
+    private execute;
+}
+/** Convenience factory — `createModelAffinityScheduler(client, opts)` reads better in setups. */
+declare function createModelAffinityScheduler(client: ModelAffinityClient | OllamaClient, options?: ModelAffinitySchedulerOptions): ModelAffinityScheduler;
+
+export { ATTR_GEN_AI_OPERATION_NAME, ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_MODEL, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_OLLAMA_AGENT_ITERATION, ATTR_OLLAMA_AGENT_MAX_ITERATIONS, ATTR_OLLAMA_ENDPOINT_ATTEMPT, ATTR_OLLAMA_ENDPOINT_NAME, ATTR_SERVER_ADDRESS, ATTR_SERVER_PORT, ATTR_URL_FULL, AbortableAsyncIterable, type AffinityRunningModel, Agent, type AgentChatClient, type AgentConfig, type AgentHooks, type AgentResult, type AgentRunInput, type AgentTurn, type AnswerFor, AnthropicCompatClient, AnyTool, type BackoffOptions, BalanceRequestOptions, type BalanceResponse, type BlobUploadResult, ChatRequestOptions, ChatResponse, ChatStreamResult, type ChoiceDecision, type CompactionOptions, type ContextCheck, type ContextCheckOptions, type ContextDiscoveryRequestOptions, type ContextLengthSignals, type ContextLengthSource, type ContextWindowSource, type ConversationSendOptions, ConversationSession, type ConversationSessionOptions, CopyRequestOptions, CreateRequestOptions, type CumulativeCacheStats, DEFAULT_BACKOFF, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WARNING_THRESHOLD, DEFAULT_EMBED_BATCH_SIZE, DEFAULT_EMBED_CONCURRENCY, DEFAULT_FAILOVER_CODES, DEFAULT_FETCH_BACKOFF_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT_MS, type Decision, type DefineToolOptions, DeleteRequestOptions, type DiscoveredContextLength, type EmbedBatchOptions, type EmbedBatchResult, EmbedRequestOptions, EmbedResponse, EmbeddingsRequestOptions, EmbeddingsResponse, type EndpointHealth, type EndpointHealthCheckResult, EndpointRegistry, type EndpointRegistryOptions, FetchLike, type FetchWithBackoffConfig, FormatOption, type FormattedTelemetry, GEN_AI_SYSTEM_OLLAMA, GenerateRequestOptions, GenerateResponse, GenerateStreamResult, type HistorySanitizeOptions, HttpClient, IMAGE_TOKEN_ESTIMATE, type IncludedBalance, KEEP_ALIVE_INDEFINITE, KEEP_ALIVE_UNLOAD, KNOWN_DONE_REASONS, type KeepAlive, type KnownDoneReason, type LegacyBalanceLimit, type LegacyIncludedBalance, type LoadMcpToolsOptions, Logger, MAX_SYSTEM_ONE_IMAGES_BYTES, MAX_SYSTEM_ONE_REQUEST_BYTES, MESSAGE_OVERHEAD_TOKENS, McpBridge, type McpBridgeOptions, McpCallToolResult, McpClientLike, McpTask, McpToolDescriptor, Message, Middleware, type ModelAffinityClient, ModelAffinityRouter, type ModelAffinityRoutingOptions, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, type ModelAffinitySnapshot, type ModelAffinityStats, type ModelCapabilities, ModelOptions, ModelResponse, ModelsClient, type NoulDecision, OLLAMA_CLOUD_BASE_URL, OLLAMA_FALLBACK_CONTEXT_LENGTH, OllamaClient, type OllamaClientConfig, type OllamaCloudFreeTierQuotaBudgets, type OllamaCredentialConfig, type OllamaEndpoint, OllamaStream, OllamaStreamEvent, OllamaStreamEventType, OpenAICompatClient, type OversizedEmbedInput, type ParallelToolCallBehavior, PingResult, ProgressResponse, ProgressStreamResult, PsResponse, PullRequestOptions, PushRequestOptions, QuotaManager, type QuotaManagerOptions, type QuotaWindowConfig, type QuotaWindowStatus, RETRYABLE_STATUS_CODES, type RankResult, type RawOllamaMetrics, RawUsageSource, RequestCancellationOptions, RequestLifecycleHook, RequestRunner, type ResponsesCreateRequest, type ResponsesCreateResponse, ResponsesModule, type ResponsesReasoningEffort, type ResponsesStreamEvent, type ResponsesToolDefinition, type ResponsesUsage, type RetryConfig, type RuntimeMode, type ScoreDecision, type SessionCompactionOptions, type SessionCompactionResult, type SessionTurn, ShowRequestOptions, ShowResponse, type SpanAttributeValue, type SpanAttributes, StatusResponse, type SupportedSchema, type SystemOneAnswer, type SystemOneAnswers, SystemOneChoiceAnswer, SystemOneChoiceQuestion, SystemOneContent, SystemOneNoulAnswer, SystemOneNoulQuestion, type SystemOneQuestion, type SystemOneQuestions, type SystemOneRequest, type SystemOneResponse, SystemOneScoreAnswer, SystemOneScoreQuestion, type SystemOneUsage, ThinkValue, ThinkingMetadata, type TimeoutSignal, TokenUsage, Tool, ToolCall, ToolCallAccumulator, ToolDefinition, ToolExecutionResult, ToolHandler, ToolParameters, ToolRegistry, type TurnCacheStats, type UsageBucket, type UsageMetrics, UsageRequestOptions, type UsageResponse, VersionResponse, VisionInput, WebFetchRequestOptions, WebFetchResponse, WebSearchRequestOptions, WebSearchResponse, addSpanEvent, batchEmbed, calculateBackoff, canonicalToolCallSignature, checkChatContext, checkEndpointHealth, checkGenerateContext, compactConversationHistory, contextWarningMessage, createDecision, createModelAffinityScheduler, createOllamaCloudFreeTierQuota, createTimeoutSignal, defineTool, detectModelCapabilities, embedBatchOverflowMessage, encodeImage, estimateChatRequestTokens, estimateGenerateRequestTokens, estimateMessageTokens, estimateSystemOneRequestBytes, estimateTokens, extractContextLength as extractNativeContextLength, extractParameterNumCtx, fetchWithBackoff, findOversizedEmbedInputs, findRunningModelContextLength, formatTelemetry, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isModelResident, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };