@nemesis-oss/ollama-sdk 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## [1.11.0] — Documentation digest + production-readiness audit: context discovery, compaction, affinity scheduling, agent cycle detection, URL-join hardening, vision-history hygiene
+
+Three real gaps from the follow-up documentation digest on concurrency & memory-scaling mechanics (see [ADR 0026](./docs/adr/0026-context-discovery-history-compaction-model-affinity.md)) and three verified findings from the October 9 production-readiness audit on agent-loop ergonomics, transport hardening, and multi-turn memory retention (see [ADR 0027](./docs/adr/0027-agent-cycle-detection-url-join-history-hygiene.md)) — all additive, no breaking changes; 778 pre-existing tests stay green, 87 new tests added (40 digest + 47 audit). Stale claims in both reports were verified against the codebase and answered with documentation and tests instead of new code (one digest claim, two audit claims).
+
+### Dynamic context-window discovery (`src/context-discovery.ts` + `models.getContextLength()`)
+
+- **`client.models.getContextLength({ model, skipRunningCheck?, signal?, timeoutMs? })`** resolves the real window instead of 2048/4096 guesswork, by precedence: the **allocated window of the running instance** (`GET /api/ps` `context_length` — exact, reflects the Modelfile default and what fit in memory) → the **Modelfile `num_ctx` default** (`POST /api/show` `parameters`) → the **native GGUF maximum** (`model_info["<arch>.context_length"]` — a ceiling, not an expectation; the official API examples show 131072 native vs 4096 allocated) → the conservative 2048 fallback.
+- Returns every signal it found — `{ contextLength, source, runningContextLength?, parameterContextLength?, nativeContextLength? }` — so "how much headroom could I raise" and "what do I have right now" are both answered. Tag-less model names match their tagged `/api/ps` entries the way Ollama itself resolves them; a 404 from `/api/ps` degrades to the `/api/show` signals instead of failing.
+- Pure pieces exported for callers holding raw responses: `resolveContextLength`, `extractParameterNumCtx`, `findRunningModelContextLength`, `extractNativeContextLength` (the existing capabilities scanner, now public). `ps()` also gained optional `{ signal, timeoutMs }` cancellation; `client.getContextLength` mirrors the models method.
+
+### Sliding-window conversation compaction (`compactConversationHistory` + `session.compact()`)
+
+- **`compactConversationHistory(messages, { maxEstimatedTokens, reserveForReply?, minTailMessages? })`** — pure helper keeping the leading system message(s) plus the newest turns that fit, dropping the oldest in between. Estimates via the same CJK-aware heuristic as the pre-flight checks (message overhead, `tool_calls`, `IMAGE_TOKEN_ESTIMATE` per image included); `minTailMessages` (default 2) guarantees the newest exchange survives even when oversized — the SDK never reproduces the server's silent truncation.
+- **`session.compact(options?)`** applies it in place, defaulting the budget to the session's `num_ctx` (or the 2048 fallback) minus a 10% reply reservation, and returns `{ droppedMessages, estimatedTokensBefore, estimatedTokensAfter, effectiveBudget }`. Cumulative cache tallies are deliberately never reset — the one-turn `evaluatedTokens` spike after compaction is the visible cost of the KV-prefix invalidation, and compaction stays **manual, never automatic** (see ADR 0026 for the tradeoff).
+
+### Model-affinity scheduling (`src/affinity.ts` + `ModelAffinityScheduler`)
+
+- Groups async work into **per-model serial queues** with a **distinct-model cap** (`concurrentModels`, default 1) and **per-model parallelism** (`perModelConcurrency`, default 1 — mirror `OLLAMA_NUM_PARALLEL`). Dispatch is **affinity-sticky**: a queued model that is already active deepens before the next model loads, because deepening avoids an unload/cold-load swap — the anti-thrashing order for `OLLAMA_MAX_LOADED_MODELS`-bounded daemons.
+- **Candidate lists** — `run(['a', 'b'], (model) => …)` picks whichever candidate is already loaded per a TTL-cached `GET /api/ps` (default 30s); single-model tasks never touch `/api/ps`, and a failing lookup degrades to the first candidate without caching the failure.
+- Tasks are caller-owned (no retry/timeout/failover injected); a rejected task rejects only its own `run()`. `stats` exposes `{ activeModels, queuedTasks }`; `dispose()` resolves once every queue drains; invalid options and candidate lists fail fast with `OllamaClientError`.
+
+### Capacity-planning documentation
+
+- New README section mapping the official FAQ's server knobs — `OLLAMA_NUM_PARALLEL` (KV memory scales `NUM_PARALLEL × CONTEXT_LENGTH`), `OLLAMA_MAX_LOADED_MODELS` (3× GPUs), `OLLAMA_MAX_QUEUE` (512 → 503s), `num_ctx` — to their client-side counterparts (`endpointHealth.maxConcurrentPerEndpoint`, `embedBatch`, `ModelAffinityScheduler`, `ToolRegistry.maxConcurrency`, `getContextLength` + pre-flight + compaction), with a note on `OLLAMA_KV_CACHE_TYPE`. One audit-digest claim was stale and is documented as already-covered instead: the SDK's request path has capped and queued per endpoint since `endpointHealth` landed — `maxConcurrentRequests`-style pooling exists as `maxConcurrentPerEndpoint`.
+
+### Agent cycle detection (`Agent` `maxRepeatedToolCalls`) — AGN-01
+
+- Audit verification first: `Agent` was already a boundary-checked runner — `maxIterations` (default 10) with `OllamaAgentMaxIterationsError`, opt-in `maxToolCalls`, and registry-side encapsulation of every tool failure (unregistered names, argument-validation failures, timeouts, thrown errors) as failed `ToolExecutionResult`s fed back as `role: 'tool'` messages — the loop never crashes on a rejection. The real gap: a _stuck_ model (re-emitting one identical call, ignoring its own results) was indistinguishable from a slow one and burned the whole iteration budget with a generic error.
+- **`AgentConfig.maxRepeatedToolCalls`** (opt-in, like `maxToolCalls`): a per-signature execution budget. Identity is the **canonical signature** — `canonicalToolCallSignature()` (newly exported) renders `name(args)` with recursively key-sorted arguments, so key reordering never splits one repeated call into several, while progressing calls (different arguments) never trip. Failed, unregistered, and timed-out executions count: re-calling a failing tool with unchanged arguments is exactly the loop this catches.
+- Enforcement is batch-preflight, mirroring `maxToolCalls`: checked before the batch executes and before `onToolCallStart` fires (hook pairing stays consistent; duplicate calls within one batch see each other). Exceeding the budget throws **`OllamaAgentToolLoopError`** (`code: 'agent_tool_loop_detected'`, never retryable) with `toolName`, `repeatedExecutions`, `maxRepeatedToolCalls`, and the canonical `signature` truncated at 200 chars — a fail-fast diagnosis at turn N+1 instead of a generic burnout at `maxIterations`.
+- 19 new tests: signature canonicalization (key-order invariance, array-order significance), off-by-default behavior preserved, fail-fast economics (3 model turns instead of 10), distinct-argument progression, within-batch duplicates, failed/unregistered executions counting, hook pairing, error hierarchy and truncation, `RangeError` validation — plus the audit's checklist item: an **end-to-end mock-server test** proving an unregistered tool name is encapsulated as a failed tool result, fed back to the model, and the run converges.
+
+### Reverse-proxy subpath hardening (`src/transport/url.ts`) — URL-01
+
+- Audit verification first: the claimed `new URL(path, base)` dispatch never existed — `HttpClient` always concatenated `baseUrl + path` and `normalizeBaseUrl` always preserved mount prefixes (unit-tested since the failover work). The real gaps: the exactly-one-slash join invariant was implicit (a future path without its leading slash would silently produce `hostapi/chat`), and nothing proved gateway subpaths end-to-end on the wire.
+- **`joinUrlPath(baseUrl, path)`** now owns the join for all three `HttpClient` request methods (`request`, `requestSseStream`, `requestStream`): collapses trailing/leading slashes, joins with exactly one slash, preserves query strings — byte-identical output for every well-formed input, hardened against malformed ones. The module documents the WHY at the point of use: WHATWG `new URL('/api/chat', 'https://gw/ai/ollama')` discards the `/ai/ollama` mount; the SDK never constructs request URLs that way.
+- 16 new tests pin the behavior at three levels — `joinUrlPath` units (including the audit's exact `https://gateway.internal.corp/ai/ollama` scenario and a WHATWG-hazard regression test), `HttpClient` transport URLs (incl. query-string paths and `requestStream`), and end-to-end `OllamaClient` wire URLs for `/api/chat`, `/api/generate`, OpenAI-compat `/v1/chat/completions`, and scheme-less subpath hosts (`proxy.internal:8080/ollama/`). README gained a "Hosting Behind a Reverse Proxy" section.
+
+### Vision-history image eviction (`sanitizeHistoryForNextTurn`) — CTX-01
+
+- Audit verification first: every mutation claim was false — `Agent` copies `input.messages`, `ConversationSession` freezes and copies on read, `client.chat` maps encoded messages into new arrays, `withEncodedMessageImages` is allocation-free on passthrough. The real gap: consumer-managed vision histories had no way to evict stale image payloads, and `/api/chat` is stateless — every prior base64 image is re-sent and re-billed (context tokens, upload bytes, heap) on every turn, forever.
+- **`sanitizeHistoryForNextTurn(messages, { keepImagesOnLastMessages?, imagePlaceholder? })`** — pure helper returning a copy with `images` evicted outside a trailing keep-window (default 1: the rolling one-image window), conversation text fully preserved, optional placeholder note so the model can tell an image used to exist. Input arrays never mutated; untouched and kept messages reused by reference.
+- Same philosophy as compaction (ADR 0026): **caller-initiated, never automatic**, because the tradeoffs are workload-specific — the model loses access to evicted images, and eviction invalidates the KV prompt prefix from that point. 12 new tests: default eviction + text preservation, purity and reference-stability, keep-windows (0/N/negative clamp), placeholder behavior (incl. empty content), empty-`images` and `Uint8Array` passthrough, and a wire-level proof that a sanitized history sent through `client.chat` carries no stale base64 while the trailing image survives.
+
+## [1.10.0] — Production-readiness audit: batched embedding pipeline, client teardown, type-declaration hardening
+
+Three findings from the daily production-readiness audit (see [ADR 0025](./docs/adr/0025-embedding-batching-client-teardown-declaration-portability.md)) — all additive, no breaking changes; 749 pre-existing tests stay green, 29 new tests added.
+
+### Batch-constrained embedding pipeline (`src/embed-batch.ts` + `client.embedBatch()`) — EMB-01
+
+- **`client.embedBatch({ model, input, batchSize?, concurrency?, … })`** for high-volume RAG/vector ingestion: splits any corpus into bounded `/api/embed` batches (defaults: 32 inputs × 3 in flight) instead of `Promise.all` floods that OOM local daemons, contend sockets, and saturate `OLLAMA_MAX_QUEUE` (503s).
+- **Order-preserving** — `embeddings[i]` always corresponds to `input[i]` regardless of batch completion order; safe to zip straight into a vector store.
+- **Fail-fast** — the first batch error aborts its in-flight siblings (each still riding the client's full failover/retry/auth/telemetry pipeline) and rejects the whole operation with the _original_ error, so a half-indexed corpus never looks like success. Caller `signal` cancels queued and in-flight batches alike (`code: 'aborted'`).
+- **Per-string context-window pre-flight** — Ollama _silently truncates_ embedding inputs longer than `num_ctx`; `embedBatch()` injects `defaultContextLength` as `num_ctx` and warns (or throws under `onContextOverflow: 'throw'`) with the offending indexes _before_ any request is sent. No margin, unlike chat/generate: an embedding prompt is the whole input.
+- `onBatchComplete(done, total)` progress callback; `truncate`/`dimensions`/`keep_alive`/`options`/`timeoutMs` pass through per batch; new exports `batchEmbed`, `findOversizedEmbedInputs`, `embedBatchOverflowMessage`, `DEFAULT_EMBED_BATCH_SIZE`, `DEFAULT_EMBED_CONCURRENCY` + types.
+
+### Client teardown — `OllamaClient.destroy(reason)` — THD-01
+
+- One call aborts **every in-flight request, active stream, and queued capacity waiter** with `OllamaAbortError` (`code: 'aborted'`, message = `reason`) — the clean-exit path for `node:worker_threads`, CLI runners, and short-lived processes where dangling fetch bodies and unconsumed stream readers keep the event loop alive.
+- Streams reject their `finalResult` and release their `maxConcurrentPerEndpoint` slots via the existing `holdUntil` release path; scopes deregister the moment their work settles, so `destroy()` can tear down a stream mid-consumption but never outlives finished work.
+- Idempotent (repeat calls return `0`) and a drain, not a disable — the client stays usable afterward. Returns the number of aborted operations. Covers every surface that goes through `executeWithFailover`/`executeCloudRequest`: chat/generate/embed (+Batch), models, responses bridge, sessions, agent, usage/balance, web tools.
+
+### Type-declaration portability hardening — TYP-03
+
+- Verified (not just assumed) the dual-packaging story: `@arethetypeswrong/cli` reports zero problems across node10/node16-CJS/node16-ESM/bundler for every entry point, and the exports map already maps `import → .d.ts` / `require → .d.cts` per subpath.
+- **New `scripts/verify-consumer-types.sh`** (also in CI and `verify:release`): compiles two _real_ consumer projects against the packed tarball — a CommonJS consumer under `--module node16` (the `require` condition, exactly the TS1479 "masquerading ESM types" scenario) and an ESM consumer under `--module nodenext`.
+- **Fixed a real leak it caught**: `VisionInput` included Node's `Buffer` global, so strict consumers without `@types/node` could not compile against our declarations. Now `string | Uint8Array` — Node Buffers are `Uint8Array` subclasses and remain fully accepted (13 vision tests untouched and green) — the published declarations are free of Node ambient globals.
+
 ## [1.9.0] — Digest upgrades: vision resolver, dual-mode Responses bridge, KV-cache sessions, context safety, blob publishing, cloud usage & balance
 
 Five upgrades closing the gaps surfaced by the official Ollama documentation review (see [ADR 0024](./docs/adr/0024-digest-upgrades-vision-responses-sessions-context-blobs.md)) — plus a second-pass recheck against the current official docs (see the last section) that added the Ollama Cloud account endpoints and a missing `/api/create` field. All additive — no breaking changes; 689 pre-existing tests stay green, 60 new tests added.

package/README.md

@@ -21,14 +21,20 @@
 - 🔎 **Ollama Cloud Web Tools**: `webSearch`/`webFetch` wrap Ollama's hosted `/api/web_search` and `/api/web_fetch` tools at `ollama.com` (requires an `OLLAMA_API_KEY`), independent of any local `baseUrl`.
 - 💳 **Ollama Cloud Usage & Balance**: `usage()`/`balance()` wrap Ollama's hosted account endpoints (`GET /api/usage`, `GET /api/balance`) — request counts, USD spend, cached-token totals bucketed by hour/day, and remaining included/purchased credits (including the legacy session/weekly plan shapes) — with the same fixed-cloud-host, API-key, timeout, and retry semantics as the web tools.
 - 🌉 **OpenAI & Anthropic Compatibility Bridges**: Built-in clients for `/v1/chat/completions`, `/v1/responses`, `/v1/models`, and `/v1/messages`, including `reasoning_effort`/`reasoning.effort` for thinking models — plus an ergonomic dual-mode `client.responses.create()` bridge that prefers native `/v1/responses` and transparently re-issues via `/api/chat` on older servers (pre-v0.13.3).
-- 💬 **KV-Cache-Aware Conversation Sessions**: `client.session(model, systemPrompt)` keeps an append-only, prefix-stable history that maximizes Ollama's KV-cache reuse across turns, and surfaces per-turn + cumulative cache hit rates (`prompt_eval_cached_count`) so cache degradation is visible instead of silent.
+- 💬 **KV-Cache-Aware Conversation Sessions**: `client.session(model, systemPrompt)` keeps an append-only, prefix-stable history that maximizes Ollama's KV-cache reuse across turns, surfaces per-turn + cumulative cache hit rates (`prompt_eval_cached_count`) so cache degradation is visible instead of silent, and offers a one-call `compact()` sliding-window escape hatch when a session outgrows its window.
 - 🛑 **Context-Window Safety**: Heuristic client-side token estimation warns (or throws, `onContextOverflow: 'throw'`) before a request is sent when the prompt approaches the effective `num_ctx` window — Ollama's default behavior is to _silently truncate_ oversized prompts — and `defaultContextLength` makes the window explicit on every request.
 - 📦 **Blob & Custom Model Publishing**: Content-addressed blob management per Ollama's documented protocol — `computeBlobDigest()` (SHA-256 → `sha256:<hex>`), `createBlobFromData()`/`createBlobFromFile()` (HEAD-check + upload, skipping existing blobs), and one-shot `createModelFromGguf()` (upload GGUF shard blobs, then `/api/create` with `files: {name: digest}`).
+- 🧵 **Batched Embeddings with Backpressure**: `client.embedBatch()` splits corpora of any size into bounded `/api/embed` batches (default 32 inputs × 3 in flight) — order-preserving, fail-fast, progress-reporting — so RAG/vector ingestion can't OOM a local daemon or saturate `OLLAMA_MAX_QUEUE` the way `Promise.all` floods do, with per-string context-window pre-flight against silent truncation.
+- 🧹 **Client Teardown (`destroy()`)**: One call aborts every in-flight request, active stream, and queued capacity waiter with `OllamaAbortError` — the clean-exit path for `worker_threads`, CLI runners, and short-lived scripts where dangling fetch bodies keep the event loop alive.
+- 🧠 **Dynamic Context-Window Discovery**: `client.models.getContextLength({ model })` resolves the real window from the server — the allocated window of the running instance (`/api/ps`), the Modelfile `num_ctx` default, and the native GGUF maximum (`model_info`), in precedence order — so applications stop hardcoding 2048/4096 guesses.
+- 🔁 **Model-Affinity Scheduling**: `ModelAffinityScheduler` runs multi-model workloads through per-model serial queues with a distinct-model cap (default 1), deepening the already-hot model before loading the next — the anti-thrashing order for `OLLAMA_NUM_PARALLEL`/`OLLAMA_MAX_LOADED_MODELS`-bounded daemons — and routes candidate lists to whichever model is already loaded.
+- 🛡️ **Agent Loop Guardrails**: `Agent` is a boundary-checked runner out of the box — `maxIterations` (default 10), an opt-in `maxToolCalls` budget, and opt-in **cycle detection** (`maxRepeatedToolCalls`) that fails fast with `OllamaAgentToolLoopError` the moment the model re-emits one identical tool call instead of burning the whole iteration budget on it; tool rejections (including unregistered names) are always encapsulated as `role: 'tool'` results, never loop crashes.
+- 🧼 **Vision History Hygiene**: `sanitizeHistoryForNextTurn()` evicts stale base64 image payloads from consumer-managed multi-turn vision histories — every `/api/chat` request re-sends the whole history, so old images silently bloat payload, context, and heap; the helper keeps images only on the trailing window you choose, conversation text fully preserved.
 - 🌊 **Web Stream Adapters**: Drop-in adapters (`toTextStream`, `toDataStream`, `toResponse`) for Next.js Route Handlers and Vercel AI SDK.
 - 📈 **OpenTelemetry Instrumentation**: Automatic spans for HTTP requests, endpoint failover, chat/generate calls, and agent runs — zero-cost when OpenTelemetry isn't installed.
 - 📊 **Client-Side Quota Monitoring**: `QuotaManager` tracks token/request usage against budgets you configure across rolling windows (e.g. Ollama Cloud's 5-hour session / 7-day weekly resets) and fails fast with `OllamaQuotaExceededError` before a request is sent.
 - ⚡ **Edge Runtime Verified**: CI bundles and runs the client in a real Edge Runtime sandbox (Cloudflare Workers/Vercel Edge-compatible) with zero Node.js APIs.
-- 📦 **Dual ESM & CJS Build**: Full module support with clean TypeScript `.d.ts` declaration maps.
+- 📦 **Dual ESM & CJS Build**: Full module support with paired `.d.ts`/`.d.cts` declarations mapped through conditional `exports` — verified in CI by `@arethetypeswrong/cli` **and** by compiling real CommonJS (node16) and ESM (nodenext) consumer projects against the packed tarball.
 - 🧩 **Contract-First Architecture**: A single canonical IR (`contracts/ir/ollama.ir.json`) drives TypeScript interfaces, generated API classes (`NativeApi`/`OpenAIApi`/`AnthropicApi`), MCP tool descriptors, Zod schemas, and field-level parity verification. New Ollama endpoints (like `/v1/systemone`) are caught automatically by bidirectional endpoint discovery. See [ADRs 0013-0019](./docs/adr/README.md).
 
 ---
@@ -188,6 +194,21 @@ npm install @nemesis-oss/ollama-sdk zod
 
 `zod` is a peer dependency (`^3.22.0 || ^4.0.0`) — install whichever major version your project already uses instead of getting a second copy bundled in.
 
+### Hosting Behind a Reverse Proxy (subpath mounts)
+
+Point `baseUrl` (or `OLLAMA_HOST`) at the mount point and every request path joins underneath it — `/api/chat`, the OpenAI/Anthropic compatibility routes (`/v1/...`), streaming, and generated-surface operations all preserve the prefix:
+
+```typescript
+// Ollama behind https://gateway.internal.corp/ai/ollama →
+// requests go to https://gateway.internal.corp/ai/ollama/api/chat, etc.
+const client = new OllamaClient({ baseUrl: 'https://gateway.internal.corp/ai/ollama' });
+
+// Scheme-less gateway hosts with subpaths normalize too:
+// 'proxy.internal:8080/ollama' → http://proxy.internal:8080/ollama/api/chat
+```
+
+The transport deliberately never uses `new URL(path, base)` — WHATWG semantics discard the base's path segments for absolute paths (`new URL('/api/chat', 'https://gw/ai/ollama')` → `https://gw/api/chat`). URL assembly is owned by a single join helper with an exactly-one-slash invariant, pinned by tests at the unit, transport, and client levels (see `src/transport/url.ts`).
+
 ---
 
 ## Quick Start
@@ -318,6 +339,125 @@ const client = new OllamaClient({
 
 The estimators are exported for custom pipelines: `estimateTokens(text)` (CJK-aware — ~1 token per CJK character, ~4 chars/token elsewhere), `estimateChatRequestTokens(req)` / `estimateGenerateRequestTokens(req)` (message overhead + tool schemas + `IMAGE_TOKEN_ESTIMATE` per image), and the underlying `checkChatContext` / `checkGenerateContext` / `contextWarningMessage`. All are heuristics (±20–30%) — for exact counts, ask the server (`prompt_eval_count`).
 
+### Discovering the Real Context Window
+
+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 the window the **running instance actually allocated** (exact, reflects the Modelfile `num_ctx` default and what fit in memory), while `POST /api/show` exposes the Modelfile's `num_ctx` default _and_ the model's **native GGUF maximum** in `model_info["<architecture>.context_length"]` — the official API examples show a model with a 131072-token native max whose running instance allocated 4096, a 32× gap. `getContextLength()` consults them in precedence order and returns every signal it found:
+
+```typescript
+const window = await client.models.getContextLength({ model: 'gemma4' });
+// -> { contextLength: 4096,        // program against this — resolved by precedence
+//      source: 'running',          // 'running' | 'parameters' | 'model-info' | 'fallback'
+//      runningContextLength: 4096, // allocated by the loaded instance (when loaded)
+//      nativeContextLength: 131072 } // the ceiling you could raise num_ctx toward
+
+// The canonical wiring — make the client's own pre-flight checks exact:
+const client = new OllamaClient({ defaultContextLength: window.contextLength });
+
+// Or raise the window deliberately when the model supports it (native max):
+await client.chat({
+  model: 'gemma4',
+  messages,
+  options: { num_ctx: window.nativeContextLength }, // 131072 — needs VRAM to match
+});
+```
+
+`skipRunningCheck: true` skips the `/api/ps` round-trip (e.g. cloud/compat-only endpoints); a 404 from `/api/ps` is treated as "not running" and never fails the lookup. The pure pieces — `resolveContextLength()`, `extractParameterNumCtx()`, `findRunningModelContextLength()`, `extractNativeContextLength()` — are exported for callers that already hold `ps`/`show` responses.
+
+### Compacting Long Conversations
+
+Sessions grow monotonically; windows don't. When `cacheStats.hitRate` collapses while history grows — or the pre-flight warnings above start firing — `compact()` is the explicit fix: it keeps the pinned system prompt plus the most recent turns that fit the budget, dropping the oldest turns in between.
+
+```typescript
+const session = client.session('llama3.1', 'You are terse.', {
+  options: { num_ctx: 4096 },
+});
+
+// …many turns later…
+const result = session.compact();
+// -> { droppedMessages: 14, estimatedTokensBefore: 4180,
+//      estimatedTokensAfter: 3552, effectiveBudget: 3686 }  // num_ctx − 10% reply reserve
+
+// Or compact any message array with an explicit budget (the pure helper):
+import { compactConversationHistory } from '@nemesis-oss/ollama-sdk';
+const kept = compactConversationHistory(session.getMessages(), {
+  maxEstimatedTokens: 4096,
+  reserveForReply: 512, // headroom for the model's next reply
+  minTailMessages: 2, // never drop the latest exchange (default)
+});
+```
+
+Compaction is deliberately **manual, never automatic**: rewriting the history invalidates the prompt prefix, so the next turn starts with a cold KV cache (visible as a one-turn `evaluatedTokens` spike in `cacheStats`). That recompute-for-a-fitting-window tradeoff is sometimes exactly right and sometimes wasteful — the SDK surfaces the numbers and leaves the call to you. Estimates use the same CJK-aware heuristic as the pre-flight checks (tool calls and images included); `minTailMessages` (default 2) guarantees the newest exchange survives even when oversized.
+
+### Evicting Stale Images from Vision Histories
+
+`/api/chat` is stateless — every request re-sends the whole history, base64 images
+included, and every image costs real context tokens on every turn. A consumer-managed
+vision history therefore re-uploads each photo long after the model answered the
+question that needed it. `sanitizeHistoryForNextTurn()` is the explicit fix — a pure
+helper that evicts image payloads from every message outside a trailing keep-window,
+conversation text fully preserved:
+
+```typescript
+import { sanitizeHistoryForNextTurn } from '@nemesis-oss/ollama-sdk';
+
+history.push({ role: 'user', content: 'What is in THIS photo?', images: [newImage] });
+
+// Old images evicted, only the trailing turn keeps its payload:
+await client.chat({ model: 'llava', messages: sanitizeHistoryForNextTurn(history) });
+
+// Keep a wider window, and tell the model what used to be there:
+sanitizeHistoryForNextTurn(history, {
+  keepImagesOnLastMessages: 2,
+  imagePlaceholder: '[image from an earlier turn removed to save context]',
+});
+```
+
+The same philosophy as compaction — caller-initiated, never automatic — with the same
+visible tradeoffs (the model loses access to evicted images; the KV prefix diverges at
+the eviction point, so a hot cache-friendly session shouldn't sanitize). Input arrays
+and untouched messages are never mutated; kept messages are reused by reference. See
+[ADR 0027](./docs/adr/0027-agent-cycle-detection-url-join-history-hygiene.md).
+
+### Model-Affinity Scheduling (multi-model anti-thrashing)
+
+Ollama's concurrency model (per the official FAQ) makes same-model parallelism cheap — KV cache scales as `OLLAMA_NUM_PARALLEL × context_length` for the _loaded_ model — but switching models is expensive: a request for a different model queues until the first goes idle or is evicted (`OLLAMA_MAX_LOADED_MODELS`, default 3× GPU count), paying an unload/cold-load swap each time. Workloads that interleave models arbitrarily (extraction on a coder model, reasoning on a thinking model) thrash the daemon that way. `ModelAffinityScheduler` is the client-side fix:
+
+```typescript
+import { ModelAffinityScheduler } from '@nemesis-oss/ollama-sdk';
+
+const scheduler = new ModelAffinityScheduler(client, {
+  concurrentModels: 1, // one model hot at a time (default) — the anti-thrash setting
+  perModelConcurrency: 1, // mirror the daemon's OLLAMA_NUM_PARALLEL if you raise it
+});
+
+// Per-model serial queues; the active model deepens before the next one loads:
+await scheduler.run('deepseek-r1', () => reason(client));
+await scheduler.run('qwen2.5:coder', () => extract(client));
+
+// Candidate lists: picks whichever model is already loaded (GET /api/ps, TTL-cached):
+const code = await scheduler.run(['qwen2.5:coder', 'qwen2.5:14b'], (model) =>
+  extractWith(client, model),
+);
+
+scheduler.stats; // { activeModels: ['deepseek-r1'], queuedTasks: 3 }
+await scheduler.dispose(); // waits for every queue to drain
+```
+
+Dispatch 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 are your own functions — the scheduler adds no retry, timeout, or failover, and a rejected task only rejects its own `run()` promise. Candidate selection degrades gracefully: if `/api/ps` fails, the first candidate runs and the failure is never cached.
+
+### Capacity Planning: OLLAMA_NUM_PARALLEL, MAX_QUEUE & KV-Cache Memory
+
+The server-side knobs (official FAQ defaults) and the client-side surfaces that map onto them:
+
+| Server knob                         | Default                   | Effect                                                                                                                                                     | Client-side counterpart                                                                                                                                                       |
+| ----------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OLLAMA_NUM_PARALLEL`               | 1                         | Parallel requests **per loaded model**; required memory scales `NUM_PARALLEL × CONTEXT_LENGTH` (a 4K-context model at 4 parallel allocates a 16K KV cache) | `ModelAffinityScheduler({ perModelConcurrency })`, `ToolRegistry({ maxConcurrency })` for agent tool dispatch                                                                 |
+| `OLLAMA_MAX_LOADED_MODELS`          | 3× GPUs (3 on CPU)        | Concurrently loaded models; beyond it, requests queue until a model goes idle or is evicted — the swap/thrash cycle                                        | `ModelAffinityScheduler({ concurrentModels })` — keep the working set small; `client.models.pin()`/`unload()` for explicit lifecycle                                          |
+| `OLLAMA_MAX_QUEUE`                  | 512                       | Queued requests beyond this are rejected immediately with **503**                                                                                          | `endpointHealth.maxConcurrentPerEndpoint` (queue client-side instead of saturating the daemon), `embedBatch({ batchSize, concurrency })` for ingestion, retry/failover on 503 |
+| `OLLAMA_CONTEXT_LENGTH` / `num_ctx` | 2048–4096 model-dependent | The window per request — prompts beyond it are **silently truncated**                                                                                      | `models.getContextLength()` for the real number, `defaultContextLength` to make it explicit, pre-flight warnings + `session.compact()` to stay inside it                      |
+
+The two failure modes this table prevents: `Promise.all`-style floods (hundreds of simultaneous requests → queue saturation → 503s, VRAM spikes) and model ping-pong (alternating models → repeated unload/reload stalls). The SDK's request path already caps and queues per endpoint via `endpointHealth` — including `strategy: 'least-connections'` for pools — and `embedBatch`/`ModelAffinityScheduler` extend that discipline to ingestion and multi-model workloads. `OLLAMA_KV_CACHE_TYPE` (`f16`/`q8_0`/`q4_0`) trades KV precision for memory headroom at the daemon level; benchmark its latency impact against these client-side levers before relying on it for throughput.
+
 ### Blob Management & Custom GGUF Model Publishing
 
 Ollama's documented import protocol: push a blob for each file, then reference it in `/api/create`'s `files` map by file name and SHA-256 digest. The SDK wraps the whole flow:
@@ -462,6 +602,31 @@ console.log(
 
 `embed()` targets the modern `/api/embed` endpoint (batch `input`, `truncate`, and `dimensions` truncation are all supported). The older single-prompt `/api/embeddings` is still available as `client.embeddings()`, but it's `@deprecated` — Ollama's own docs consider it legacy in favor of `/api/embed`.
 
+#### Batched embeddings with backpressure (large corpora)
+
+Embedding a whole corpus with `Promise.all(chunks.map(c => client.embed(...)))` is the failure mode every RAG pipeline eventually hits: hundreds of simultaneous requests contend sockets, saturate the daemon's request queue (`OLLAMA_MAX_QUEUE` → 503s), and spike GPU VRAM as the model instance serves every prompt at once. Long inputs have a second, quieter failure mode — Ollama **silently truncates** any input string longer than the model's context window unless `truncate: false` is set.
+
+`embedBatch()` is the safe building block for ingestion:
+
+```typescript
+const { embeddings, batchCount } = await client.embedBatch({
+  model: 'nomic-embed-text:latest',
+  input: corpus, // any size — 10 strings or 10 million
+  batchSize: 32, // inputs per /api/embed request (default 32)
+  concurrency: 3, // batches in flight simultaneously (default 3)
+  keep_alive: '10m', // pin the model for the whole ingestion
+  onBatchComplete: (done, total) => progress.log(`${done}/${total} batches`),
+});
+
+// embeddings[i] always corresponds to corpus[i], no matter which batch
+// finished first — safe to zip straight into a vector store.
+await vectorStore.upsert(corpus.map((text, i) => ({ id: i, text, vector: embeddings[i] })));
+```
+
+Every batch rides the client's full pipeline — failover, retry, auth, telemetry — and the operation is **order-preserving** and **fail-fast**: the first batch error aborts its in-flight siblings and rejects the whole call with the original error, so a half-indexed corpus never looks like success. The caller's `signal` cancels queued and in-flight batches alike (`code: 'aborted'`).
+
+Like `chat`/`generate`, `embedBatch()` injects `defaultContextLength` as `num_ctx` and pre-checks each input string's estimated tokens against the resolved window — warn (default) or throw (`onContextOverflow: 'throw'`) with the offending indexes _before_ any request is sent, since Ollama truncates embedding inputs silently. Tune `batchSize`/`concurrency` per daemon: lower both for a laptop GPU, raise `concurrency` for remote or multi-endpoint clients.
+
 ### Model Lifecycle Management
 
 Full parity with Ollama's model catalog and blob-store API — every method targets one specific endpoint's local state and deliberately does **not** cross-endpoint fail over (see [ADR 0008](./docs/adr/0008-endpoint-failover-scope.md)):
@@ -571,6 +736,43 @@ synthesizes a stable client-side ID for tracing and execution correlation:
 use Ollama's documented `tool_name` field; the SDK-local `toolCallId` is not sent on
 the wire. See [ADR 0007](./docs/adr/0007-synthetic-tool-call-ids.md).
 
+The loop is boundary-checked by construction. `maxIterations` (default 10) bounds the
+run; an optional `maxToolCalls` budget caps total executions; and tool rejections never
+crash the loop — the registry encapsulates unregistered names, argument-validation
+failures, timeouts, and thrown errors as failed `ToolExecutionResult`s that are fed
+back to the model as ordinary `role: 'tool'` messages so it can self-correct. When a
+model gets _stuck_ — re-emitting the same call with unchanged arguments instead of
+reacting to its results — opt-in cycle detection fails fast with a precise diagnosis
+instead of letting the loop burn its whole budget on the same wasted call:
+
+```typescript
+import { Agent, OllamaAgentToolLoopError } from '@nemesis-oss/ollama-sdk';
+
+const agent = new Agent(client, {
+  tools: registry,
+  maxIterations: 10,
+  maxToolCalls: 40, // total execution budget across the run
+  maxRepeatedToolCalls: 3, // per identical call (same name + same arguments)
+});
+
+try {
+  const result = await agent.run({ model: 'qwen3:8b', messages });
+} catch (error) {
+  if (error instanceof OllamaAgentToolLoopError) {
+    // The model re-emitted error.toolName with identical arguments a 4th time.
+    // error.signature holds the canonical call; error.repeatedExecutions the count.
+    // Fail fast at turn 4 instead of burning all 10 iterations on it.
+  }
+}
+```
+
+Counting is per canonical signature — `canonicalToolCallSignature()` (also exported)
+sorts argument keys recursively, so a model re-emitting the same call in a different
+key order still counts as the same call. Failed, unregistered, and timed-out
+executions count too: re-calling a failing tool with unchanged arguments is exactly
+the pathological loop this catches. Like `maxToolCalls`, the guardrail is opt-in and
+caller-owned — see [ADR 0027](./docs/adr/0027-agent-cycle-detection-url-join-history-hygiene.md).
+
 Running several `Agent`s against different models/API keys for different roles (e.g. a
 planning model, a coding model, a research model) is a single `OllamaClient` with
 per-endpoint `models` allow-lists (see
@@ -962,6 +1164,37 @@ initial HTTP round trip:
   between turns, outside any `chat()` call, so a slow tool never ties up one of your
   scarce concurrent-request accounts.
 
+### Client Teardown: `destroy()`
+
+Inside `node:worker_threads` tasks, CLI runners, serverless handlers, and other
+short-lived processes, the things that keep an event loop (and therefore the
+thread or process) alive are exactly the things this SDK manages: in-flight
+fetch bodies, unconsumed stream readers, and requests queued behind
+`maxConcurrentPerEndpoint`. `destroy()` is the one-call drain for all of them:
+
+```typescript
+import { parentPort, workerData } from 'node:worker_threads';
+
+const client = new OllamaClient({ baseUrl: workerData.ollamaUrl });
+try {
+  await processTask(client, workerData.payload);
+} finally {
+  // Aborts every request/stream still in flight with OllamaAbortError
+  // (code 'aborted'), releases their endpoint slots, and lets the worker
+  // thread exit cleanly. Idempotent — safe to call from a signal handler.
+  const aborted = client.destroy('worker task finished');
+  if (aborted > 0) logger.warn(`torn down ${aborted} in-flight operations`);
+}
+```
+
+Every aborted operation — dispatched **or** still queued — rejects with
+`OllamaAbortError` carrying the reason; active streams reject their
+`finalResult` and release their concurrency slots, so nothing dangles after
+the call returns the count of operations it aborted. `destroy()` is a drain,
+not a permanent disable: the client stays usable afterward (spawn a fresh one
+if you want a hard cut), and calling it on an idle client is a no-op that
+returns `0`.
+
 ---
 
 ### Observability with OpenTelemetry
@@ -1356,6 +1589,13 @@ npm run bench
 
 # Run full CI verification pipeline (typecheck, lint, test, build, edge runtime check)
 npm run verify
+
+# Non-disastrous smoke test: contract gates (validate, IR diff, type drift) + full
+# verify chain + package type-resolution check + real CJS/ESM consumer compile.
+# Read-only — no clean, no codegen rewriting src/generated. Live conformance runs
+# automatically if an Ollama server is reachable on localhost:11434 (otherwise
+# those tests skip cleanly).
+npm run smoke
 ```
 
 ---

package/dist/{anthropic-5oYIRS6D.d.ts → anthropic-CfricAhK.d.ts}

@@ -1,4 +1,4 @@
-import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, ae as SseEvent, x as OllamaClientError } from './runtime-C3rfpkZw.js';
+import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, af as SseEvent, y as OllamaClientError } from './runtime-CCm4CtU_.js';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.

package/dist/{anthropic-BIh45UXj.d.cts → anthropic-DinrABof.d.cts}

@@ -1,4 +1,4 @@
-import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, ae as SseEvent, x as OllamaClientError } from './runtime-D2W9TfCJ.cjs';
+import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, af as SseEvent, y as OllamaClientError } from './runtime-DTtWCxDs.cjs';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.

package/dist/{compose-DCVYMvOL.d.ts → compose-BQYXdpar.d.ts}

@@ -1,4 +1,4 @@
-import { l as ToolDefinition, i as ToolCall, n as Message } from './types-DVcX_zMp.js';
+import { l as ToolDefinition, i as ToolCall, n as Message } from './types-BtQexFpT.js';
 import { z } from 'zod';
 
 /**

package/dist/{compose-Dj6FdF2n.d.cts → compose-lt-Qz3lI.d.cts}

@@ -1,4 +1,4 @@
-import { l as ToolDefinition, i as ToolCall, n as Message } from './types-DVcX_zMp.cjs';
+import { l as ToolDefinition, i as ToolCall, n as Message } from './types-BtQexFpT.cjs';
 import { z } from 'zod';
 
 /**

package/dist/generated-api.d.cts

@@ -1,8 +1,8 @@
-import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-BIh45UXj.cjs';
-export { N as NativeApi } from './anthropic-BIh45UXj.cjs';
-import { O as OllamaRuntime } from './runtime-D2W9TfCJ.cjs';
-export { a as OperationDefinition } from './runtime-D2W9TfCJ.cjs';
-import './types-DVcX_zMp.cjs';
+import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-DinrABof.cjs';
+export { N as NativeApi } from './anthropic-DinrABof.cjs';
+import { O as OllamaRuntime } from './runtime-DTtWCxDs.cjs';
+export { a as OperationDefinition } from './runtime-DTtWCxDs.cjs';
+import './types-BtQexFpT.cjs';
 import 'zod';
 
 /**

package/dist/generated-api.d.ts

@@ -1,8 +1,8 @@
-import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-5oYIRS6D.js';
-export { N as NativeApi } from './anthropic-5oYIRS6D.js';
-import { O as OllamaRuntime } from './runtime-C3rfpkZw.js';
-export { a as OperationDefinition } from './runtime-C3rfpkZw.js';
-import './types-DVcX_zMp.js';
+import { O as OpenAIChatCompletionRequest, a as OpenAIChatCompletionResponse, b as OpenAIChatCompletionChunk, c as OpenAICompletionRequest, d as OpenAICompletionResponse, e as OpenAICompletionChunk, f as OpenAIEmbeddingRequest, g as OpenAIEmbeddingResponse, h as OpenAIListModelsResponse, i as OpenAIModelItem, j as OpenAIResponsesRequest, k as OpenAIResponsesResponse, l as OpenAIResponsesStreamEvent, A as AnthropicMessagesRequest, m as AnthropicMessagesResponse, n as AnthropicMessageStreamEvent } from './anthropic-CfricAhK.js';
+export { N as NativeApi } from './anthropic-CfricAhK.js';
+import { O as OllamaRuntime } from './runtime-CCm4CtU_.js';
+export { a as OperationDefinition } from './runtime-CCm4CtU_.js';
+import './types-BtQexFpT.js';
 import 'zod';
 
 /**