@nemesis-oss/ollama-sdk 1.10.0 → 1.11.0

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-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';
+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 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 { 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-DTtWCxDs.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-DTtWCxDs.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 { 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-DinrABof.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-DinrABof.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 { M as McpClientLike, a as McpToolDescriptor, b as McpTask, c as McpCallToolResult } from './types-CI-gM2u5.cjs';
@@ -122,6 +122,211 @@ 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;
+/**
+ * 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.
  */
@@ -445,92 +650,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 +725,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 +1055,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 +1265,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
@@ -1772,7 +2081,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>;
@@ -2607,6 +2924,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 +2975,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 +3003,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;
@@ -2796,6 +3142,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 +3202,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, 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, 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, ModelAffinityScheduler, type ModelAffinitySchedulerOptions, 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, 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 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, inferRuntimeMode, isKeepAliveSugar, isKnownDoneReason, isSameToolCall, listAllMcpTools, listAvailableModels, loadMcpTools, mergeToolCall, mergeToolCallArgumentsString, mergeToolCallArrays, normalizeChatStream, normalizeGenerateStream, normalizeKeepAlive, normalizeProgressStream, parseNdjsonStream, parseStructuredOutput, registerMcpTools, resolveContextLength, resolveCredentialEndpoints, sanitizeHistoryForNextTurn, setSpanError, toDataStream, toResponse, toTextStream, withRetry, withSpan, zodToJsonSchema };