@nemesis-oss/ollama-sdk 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # Changelog
 
+## [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.
+
+### Universal vision asset resolver (`src/vision.ts`)
+
+- **`VisionInput = string | Buffer | Uint8Array`** accepted anywhere `images` is (`Message.images`, `generate()`), implementing the official SDK vision convention: SDKs accept polymorphic sources; the REST API strictly requires raw base64 strings.
+- String resolution order: `data:image/...;base64,` data URIs (header stripped) → `http(s)://` URLs (fetched via global `fetch`, abortable through the request's `signal`) → image-extension file paths (`.png`/`.jpg`/`.webp`/…, read via **dynamically imported** `node:fs` — Node only, browser bundles unaffected; graceful passthrough when the read fails) → assume raw base64.
+- Path detection is extension-based, not slash-based — `/` is a legal base64 alphabet character, and a contains-slash heuristic would misfire on long payloads.
+- The request pipeline stays allocation-free when every entry is already base64 (`withEncodedImages` returns the same array reference).
+- Previously-broken inputs are silently fixed: data-URI strings, which used to ship the `data:image/...;base64,` header to the server, are now stripped.
+- New exports: `resolveImageInput()`, `imageStringNeedsResolution()`, `resolveImages()`, `type VisionInput`.
+
+### Dual-mode OpenAI Responses bridge (`src/responses.ts`)
+
+- **`client.responses.create()`** — ergonomic, OpenAI-SDK-shaped bridge (`model`, `input`, `instructions`, `tools`, `temperature`, `top_p`, `max_output_tokens`, `reasoning_effort`, `think`) over `POST /v1/responses` (Ollama ≥ v0.13.3), with **transparent `/api/chat` fallback on 404** for older servers: `instructions` → system message, `max_output_tokens` → `options.num_predict`, reply normalized back into the Responses shape (`output_text`, `usage.input_tokens`/`output_tokens`). The result's `transport` field (`'native' | 'chat-adapter'`) records the path taken.
+- **`client.responses.stream()`** — lazy async generator yielding simplified `{type: 'text_delta' | 'thinking_delta' | 'done'}` events; same dual-mode transport, fallback only on establishment failure (never mid-stream, which would duplicate consumed deltas).
+- **`client.responses.createText()`** — convenience returning just the output text.
+- Native-mode mapping extracts joined `output_text` blocks (including refusals), reasoning traces (`thinking`), and parsed `function_call` items (`tool_calls` with parsed `arguments` objects).
+- 404-only fallback, deliberately: 5xx remains a retryable error for the existing retry policy; 4xx is a request bug — neither means "endpoint absent."
+- The full wire-shaped surface stays on `client.openai.responses()`; this module is the ergonomic migration subset documented in the new **MIGRATION.md** (openai npm SDK → this SDK mapping table).
+
+### KV-cache-aware conversation sessions (`src/conversation.ts`)
+
+- **`client.session(model, systemPrompt?)`** (or `new ConversationSession(client, options)`) — multi-turn session with an **append-only frozen history** and a system prompt **pinned at construction** (no mutation API — a per-call system prompt is the #1 silent KV-cache killer), maximizing Ollama's prompt-prefix KV-cache reuse across turns.
+- **Per-turn and cumulative cache statistics** from `prompt_eval_cached_count` / `prompt_eval_count`: `session.cacheStats` (cumulative) and `sendTurn()`'s `TurnCacheStats` (per turn).
+- Hit-rate denominator is `cached / (cached + evaluated)`: when the entire prompt hits the cache, Ollama reports `prompt_eval_count: 0`, so dividing by `prompt_eval_count` alone would score the best case as 0%.
+- `send()` (reply text), `sendTurn()` (full turn record), `getMessages()` (defensive copy of the frozen history), `reset()` (restores system prompt, zeroes stats). Per-turn overrides (`options`, `think`, `keep_alive`, `tools`, `format`, `signal`, `timeoutMs`) ride on the request, never the history.
+
+### Context-window safety (`src/context-safety.ts`)
+
+- **Pre-flight estimation on every `chat()`/`generate()` call** guards against Ollama's silent prompt truncation when `num_ctx` is unset (server default 2048–4096, model-dependent): CJK-aware heuristic (~1 token per CJK character, ~4 chars/token elsewhere, `IMAGE_TOKEN_ESTIMATE` per image, per-message overhead, tool schemas), ±20–30% by design — no tokenizer download.
+- **`defaultContextLength`** client config — injected as `options.num_ctx` on every request that omits it, making the effective window explicit on the wire.
+- **`onContextOverflow: 'warn' | 'throw'`** (default `'warn'`) — log through the configured logger and send anyway, or reject client-side with `OllamaClientError` (`code: 'context_overflow'`) before anything hits the wire. `contextWarningThreshold` (default `0.9`) tunes the trip point.
+- Window resolution order: request `num_ctx` → client `defaultContextLength` → conservative 2048 fallback, which warns only when the estimate _outright exceeds_ it (no margin — the real server default may be 4096, and a margin would generate false positives).
+- New exports: `estimateTokens()`, `estimateChatRequestTokens()`, `estimateGenerateRequestTokens()`, `checkChatContext()`, `checkGenerateContext()`, `contextWarningMessage()`, `DEFAULT_CONTEXT_WARNING_THRESHOLD`, `IMAGE_TOKEN_ESTIMATE`, `OLLAMA_FALLBACK_CONTEXT_LENGTH`.
+
+### Blob management & custom GGUF model publishing (`src/models-client.ts`)
+
+- **`computeBlobDigest(data)`** — SHA-256 via the Web Crypto API (`crypto.subtle`, global in Node ≥ 20 and every browser/edge runtime), formatted `sha256:<64 lowercase hex>` exactly as Ollama's content-addressed store expects.
+- **`createBlobFromData(data, {digest?})`** / **`createBlobFromFile(path)`** — HEAD existence check then upload, skipping the POST (and the wasted bandwidth) when the blob is already present; returns `BlobUploadResult { digest, alreadyExisted }` (file variant adds `fileName` — the basename `/api/create`'s `files` map keys on).
+- **`createModelFromGguf(model, ggufPath | paths, opts)`** — one-shot implementation of Ollama's documented import protocol: push a blob per GGUF shard, then `POST /api/create` with `files: { <fileName>: <digest> }` (verified against the official API reference).
+
+### Docs recheck: Ollama Cloud account endpoints + contract refresh
+
+A second full audit against the current official Ollama docs (`docs/openapi.yaml`, `docs/api/*.mdx`, `docs/capabilities/*.mdx`, `docs/modelfile.mdx`, `docs/import.mdx`, `docs/context-length.mdx`) found the SDK already at parity everywhere except three items — all closed here:
+
+- **`client.usage(options?)`** — wraps `GET https://ollama.com/api/usage` (cloud-only): request counts, USD spend, and token totals (input / cached-input / output) across the whole range plus hourly (`range: '24h'`) or daily (`'7d'`/`'30d'`) buckets, including `partial: true` markers for the in-progress hour/day. Query parameters `range` (`'24h' | '7d' | '30d'`, server default `'7d'`) and `scope` (`'self' | 'team'`, server default `'self'`, team requires an admin) are typed and only sent when provided.
+- **`client.balance(options?)`** — wraps `GET https://ollama.com/api/balance`: remaining included + purchased credits, with the included shape a runtime-discriminated union of the plan-period credits object (`balance_usd`/`allowance_usd`/`period`) and the legacy session/weekly percentage-limits shape.
+- Both ride the same fixed-cloud-host pipeline as `webSearch`/`webFetch` (`https://ollama.com`, `apiKey`/`OLLAMA_API_KEY`, default timeout + retry, never multi-endpoint failover) and both endpoints' documented 10-req/min rate limit is respected by the shared `OllamaRateLimitError` retry semantics (429 + `Retry-After`).
+- **`CreateRequestOptions.capabilities`** — the one field-level gap the drift detector surfaced: the official `/api/create` payload accepts `capabilities: string[]` (e.g. `'decision'`) to add capabilities without removing inherited/inferred ones; now typed and forwarded. `files` also joined the create parity manifest.
+- **Contract refresh** — the pinned OpenAPI snapshot (`contracts/sources/ollama.openapi.yaml` + verbatim `docs/upstream/ollama-openapi.yaml`) moved from the 2026-10-02 pin to 2026-10-07 (source SHA `675c8bb`), bringing the `Usage*`/`Balance*` schemas into the IR (7 new contract-generated models), repairing the corrupted enum literals the upstream file carries (`[24h, 7d, 30d]`, `[hour, day]`), and adding a new `contracts/overlays/cloud.yaml` so bidirectional endpoint discovery, the MCP tool registry, and the IR inspector all see the account endpoints.
+- **Generator fix**: top-level `allOf` schemas (like `UsageBucket` = `UsageMetrics & {from, until, partial?}`) previously emitted as an empty interface — the models emitter dropped the intersection. `allOf` now emits a correct type alias; the Zod emitter already handled it.
+- Everything else audited clean: all 15 core REST endpoints (incl. legacy `/api/embeddings`), `/v1/systemone`, `web_search`/`web_fetch`, the full OpenAI-compat surface (incl. `reasoning_effort`, `reasoning.effort`, `think`, `instructions`, `max_output_tokens`) and Anthropic-compat surface (incl. `output_config`, thinking, tool results, all streaming events), field-level sync on every request/response schema (`logprobs`, `top_logprobs`, `think`, `remote_host`/`remote_model`, `draft_files`, `parser`, `renderer`, `requires`, Ps `context_length`/`size_vram`, Show `capabilities`/`thinking`), auth (`OLLAMA_API_KEY` scoping), and the capability docs (vision, structured outputs, thinking, embeddings, tool calling, context length, GGUF import).
+- New exports: `client.usage()`, `client.balance()`, `UsageRequestOptions`, `UsageRange`, `UsageScope`, `BalanceRequestOptions`, and the contract-generated `UsageResponse`, `UsageMetrics`, `UsageBucket`, `BalanceResponse`, `IncludedBalance`, `LegacyBalanceLimit`, `LegacyIncludedBalance`.
+- 10 new unit tests (`test/usage-balance.test.ts`, mocked fetch — CI-safe) and updated guard tests (`test/security-invariants.test.ts` host allowlist now covers the four cloud ops; `test/contract/parity.test.ts` new-ops set extended).
+
+### Documentation & examples
+
+- README: four new Quick Start sections (sessions, dual-mode Responses, context safety, blob publishing) + rewritten vision section; five new feature bullets.
+- **MIGRATION.md** (new): openai npm SDK → this SDK mapping table, responses/chat-completions/vision/statefulness/reasoning/error mapping.
+- **ADR 0024** (new) + ADR index now lists 0022–0024.
+- Five runnable examples: `examples/vision-inputs.ts`, `examples/responses-bridge.ts`, `examples/conversation-session.ts`, `examples/context-safety.ts`, `examples/blob-publishing.ts` (`npm run example <file>`) — plus `examples/usage-balance.ts` from the docs-recheck pass.
+- 50 new unit tests (mocked fetch — CI-safe, no daemon): `test/vision-resolver.test.ts`, `test/responses-bridge.test.ts`, `test/conversation-session.test.ts`, `test/context-safety.test.ts`, `test/blob-helpers.test.ts` — plus 10 more in `test/usage-balance.test.ts`.
+
+## [Unreleased]
+
+### Fix: IPv6 loopback was classified as Ollama Cloud
+
+- `inferRuntimeMode()` compared `URL.hostname` to `'::1'`, but WHATWG URL reports an IPv6 literal with its brackets (`'[::1]'`), so `http://[::1]:11434` was classified as `cloud`. Structured-output (`format`) requests to a local Ollama on IPv6 loopback were therefore refused pre-flight with `OllamaUnsupportedCapabilityError`, and `localMode` was off for capability detection. The brackets are now stripped before comparing. Public IPv6 addresses are still `cloud`.
+
+### Host normalization and scoped `OLLAMA_API_KEY`
+
+- **Base URL normalization.** `baseUrl`, `OLLAMA_HOST`, per-credential `baseUrl` and `endpoints[].baseUrl` now accept the bare forms the Ollama CLI accepts: `127.0.0.1:11434`, `0.0.0.0`, `:11434`, `myhost`. A missing scheme defaults to `http://`, a missing port on a scheme-less host defaults to `11434`, scheme-less port `443` selects `https://`, and `:port` means `127.0.0.1`. Full URLs and reverse-proxy path prefixes are unchanged. Previously a scheme-less value produced an invalid request URL.
+- **Behavior change: `OLLAMA_API_KEY` is no longer forwarded to arbitrary hosts.** The env-sourced key is applied to the default endpoint only when its host is Ollama Cloud (`ollama.com`, `*.ollama.com`) or loopback. An explicit `apiKey` is always sent, to any host. If you relied on `OLLAMA_API_KEY` for a LAN or proxied server, pass `apiKey` explicitly. Web search/fetch (always `https://ollama.com`) still use the env key.
+
+### Production-readiness audit — tool-call accumulator, mock server
+
+- **Offline wire-format conformance tests** (`test/conformance/native-api-offline.test.ts`). The sibling `native-api.test.ts` hits a REAL Ollama server and skips when none is available. The new offline tests use `OllamaMockServer` to emit contract-shaped NDJSON frames without any model inference, so they run in every CI environment — including those without an Ollama daemon. They validate ONLY the wire format (schema conformance, error-class mapping, optional-field handling), NOT model behavior. The split exists because wire-format drift is a contract concern (catchable offline), while model-behavior drift is a server/model concern (only catchable against a live server). 22 new tests covering:
+  - `GET /api/version`, `/api/tags`, `/api/ps`, `POST /api/show` schema conformance
+  - `POST /api/chat`, `/api/generate`, `/api/embed` schema conformance (non-streaming)
+  - `POST /api/chat`, `/api/generate` streaming chunk schema conformance
+  - Error-class mapping: 404 → `OllamaNotFoundError`, 503 → `OllamaOverloadedError`, in-band `{"error":"..."}` → `OllamaStreamError`
+  - Optional telemetry fields (`prompt_eval_cached_count`, `thinking`, `done_reason`) — verifies the SDK does NOT throw when these are absent (the Wave 13 conformance failure mode)
+  - `done_reason` variants: `"stop"`, `"length"`, `"load"`, `"unload"` all parse cleanly; an undocumented value also parses cleanly (forward-compat)
+  - `OllamaClient` vs `NativeApi` shape parity (mirrors the live parity test)
+- Updated `test/conformance/harness.ts` docstring to document the live-vs-offline split.
+
+### Production-readiness audit — tool-call accumulator, mock server
+
+- **Defensive tool-call streaming accumulator (`src/tools/tool-call-accumulator.ts`).** The original `aggregateChat` in `src/streaming/normalize.ts` blindly appended every chunk's `tool_calls` array, which would produce duplicate entries if Ollama ever started streaming them incrementally. The new `ToolCallAccumulator` matches entries by `id` (the SDK-synthesized stable identifier) or by array position, and merges them with spread-semantics on `function.arguments`. For the documented native Ollama behavior (tool_calls arrive complete in one chunk), the accumulator is a no-op — one chunk carries the full array, the next chunk has nothing, and the accumulator appends exactly once. The accumulator is also exported for callers who want the same merge logic on raw NDJSON chunks.
+  - New exports: `ToolCallAccumulator` class, `mergeToolCallArrays()` stateless helper, `mergeToolCall()` / `mergeToolCallArgumentsString()` / `isSameToolCall()` standalone helpers.
+  - `aggregateChat` now uses `mergeToolCallArrays` instead of the naive `[...accumulated, ...incoming]` spread.
+  - Includes a dedicated `mergeToolCallArgumentsString` helper for the OpenAI-compat streaming format (where `function.arguments` arrives as string deltas like `'{"city":'` + `' "Bengaluru"}'`); the OpenAI-compat bridge at `src/integrations/openai.ts` already does its own per-index accumulation, but the helper is exported for callers who want the same logic elsewhere.
+
+- **In-memory mock server for deterministic CI testing (`test/mocks/ollama-mock-server.ts`).** A thin `node:http` wrapper that lets tests register route handlers with programmable delay, chunk fragmentation, mid-stream error injection, and connection drops. Complements the existing VCR cassette system (`test/vcr.ts`) with capabilities cassettes can't provide:
+  - Programmable inter-chunk delay (test backpressure handling).
+  - Mid-stream error frame injection (test in-band `{"error":"..."}` trapping).
+  - Chunk fragmentation across TCP packets (test parser buffering).
+  - 503/502/429 error status codes with custom bodies.
+  - Connection drops mid-stream (test recovery from network failures).
+  - Request body capture via `onRequest` callback.
+  - Idempotent `stop()` — safe to call from `afterEach` hooks without tracking whether `start()` ran.
+  - Ephemeral port support (`port: 0`) for parallel test runs.
+
+### Second digest — mid-stream errors, 502/503 specialization, pull-progress ergonomics
+
+- **In-band stream-error trapping (NDJSON).** Ollama's streaming endpoints start with HTTP 200 OK and chunked transfer encoding; if generation fails mid-flight (GPU OOM, driver crash, context window overflow, model unload race), the server emits a final `{"error": "..."}` JSON frame and closes the stream. The HTTP status code never changes from 200, so HTTP-status-based error detection misses these errors entirely — they would silently bleed into the assistant's content stream as garbage tokens or undefined-field accesses.
+  - `parseNdjsonStream` now detects bare `{"error": "..."}` frames and throws `OllamaStreamError` immediately, with the error message preserved.
+  - `OllamaStreamError.partialContent` carries whatever content was accumulated before the error frame arrived (concatenated `message.content` for chat streams, concatenated `response` for generate streams, empty string for pull/push streams).
+  - The stream's `finalResult` promise rejects with the enriched `OllamaStreamError`; the `for await ... of stream` iterator yields an `{ type: 'error', data: { error } }` event before completing.
+  - See: https://github.com/ollama/ollama/blob/main/docs/api.md
+
+- **Granular HTTP status specialization.** Two new error subclasses give callers a way to branch on the failure mode rather than parsing messages or branching on `status` numbers.
+  - `OllamaOverloadedError` (HTTP 503) — server queue saturation (`OLLAMA_MAX_QUEUE` exceeded, default 512). `retryable: true`.
+  - `OllamaBadGatewayError` (HTTP 502) — cloud model could not be reached by the Ollama Cloud proxy. `retryable: true`.
+  - Both extend `OllamaClientError` directly (NOT `OllamaServerError`) because `OllamaServerError`'s constructor unconditionally forces `code: 'server_error'`. Callers wanting "any 5xx" should branch on `error.status >= 500 && error.status < 600` rather than `instanceof OllamaServerError`.
+  - Existing `instanceof` handlers for `OllamaNotFoundError` (404), `OllamaRateLimitError` (429), and `OllamaServerError` (generic 5xx) remain unchanged.
+
+- **Typed pull/push progress callback (`onProgress`).** The SDK already exposed pull/push progress as a typed `OllamaStream` via `models.pull({ stream: true })`. The new `onProgress(stream, cb)` helper wraps the stream iteration with a pre-computed `percent` field for callers building download/upload UIs:
+
+  ```ts
+  const stream = await client.models.pull({ model: 'llama3.2', stream: true });
+  await onProgress(stream, (event) => {
+    if (event.percent !== undefined) {
+      console.log(`${event.status}: ${event.percent}% (${event.digest?.slice(0, 12) ?? '-'})`);
+    }
+  });
+  ```
+  - `computeProgressPercent(chunk)` and `toPullProgressEvent(chunk)` exported for callers who want the percent calculation without subscribing to a stream.
+  - `PullProgressEvent` type carries `{ status, digest?, total?, completed?, percent?, raw }`.
+
+- **Cloud-vs-local tool-replay investigation (ADR 0023).** Documented the SDK's stance on parallel-vs-sequential tool-call emission from cloud vs local models: the SDK is a transparent passthrough, models decide, agent authors enforce sequential execution via `ToolRegistry`'s `maxConcurrency` option if they need it. Implemented the proposed `ModelCapabilities.parallelToolCalls` field as a best-effort heuristic:
+  - New `ParallelToolCallBehavior` union: `'yes' | 'no' | 'unknown'`.
+  - Cloud-mode + tool-capable → `'yes'` (the OpenAI/Anthropic compat bridges proxy to proprietary models that freely emit parallel tool calls).
+  - Cloud-mode + no tools → `'unknown'`.
+  - Local-mode + family in known-parallel list (`qwen2`, `qwen2.5`, `qwen3`, `llama3.1`, `llama3.2`, `llama3.3`, `llama4`, `mistral`, `mixtral`, `hermes`, `command-r`, `command-r-plus`) → `'yes'`.
+  - Local-mode + model name (including `:tag`) contains a tool-use variant hint (`tool-use`, `instruct`, `hermes`, `command-r`, etc.) → `'yes'`.
+  - Otherwise → `'unknown'` (caller should treat as "ask the model and see what it does").
+  - The family is extracted from `/api/show`'s `model_info.*.architecture` (with fallbacks to `details.family` then `details.families[0]`).
+
+### First digest — VRAM lifecycle, fetchWithBackoff, System One image caps, done_reason decoder
+
+- **VRAM lifecycle primitives.** Added ergonomic helpers for explicit GPU memory management, addressing the upstream `keep_alive` semantics documented in the Ollama FAQ:
+  - `KeepAlive` type union (`string | number | 'unload' | 'indefinite'`) and `normalizeKeepAlive()` helper map the SDK-level sugar literals `'unload'` and `'indefinite'` to the wire-level `0` and `-1` sentinels.
+  - `ModelsClient.unload(model)` issues an empty `/api/generate` request with `keep_alive: 0` to evict a model from VRAM immediately, freeing GPU memory for subsequent pipelines.
+  - `ModelsClient.pin(model)` issues an empty `/api/generate` request with `keep_alive: -1` to pre-load and pin a model indefinitely for hot-loop inference.
+  - `OllamaClient.unloadModel(model)` and `OllamaClient.pinModel(model)` convenience aliases mirror the existing `listModels` / `pullModel` pattern.
+  - `KEEP_ALIVE_UNLOAD` and `KEEP_ALIVE_INDEFINITE` exported constants for callers who want the raw sentinel values directly.
+
+- **Overload resiliency for HTTP 503 / 429.** New standalone `fetchWithBackoff()` helper wraps any fetch-shaped function with jittered exponential backoff for transient saturation responses. Mirrors the SDK's internal transport retry policy (`maxRetries: 3`, `initialDelayMs: 500`, `maxDelayMs: 30_000`, full-jitter strategy) so consumers see identical retry behavior whether they go through `OllamaClient` or call the helper directly. Useful for raw HTTP traffic to Ollama's compatibility bridges (Anthropic / OpenAI) or sibling Ollama instances outside the configured endpoint registry. `RETRYABLE_STATUS_CODES` and `DEFAULT_FETCH_BACKOFF_CONFIG` exported for downstream tooling.
+
+- **System One image support ergonomics.** The generated `SystemOneRequest.images?: readonly string[]` field (already on the wire) is now backed by:
+  - `MAX_SYSTEM_ONE_REQUEST_BYTES` (64 KiB) and `MAX_SYSTEM_ONE_IMAGES_BYTES` (32 MiB) constants documenting the conditional server-side size limits.
+  - `estimateSystemOneRequestBytes(request)` helper for pre-flight size validation before sending a multi-image batch — the runtime enforces the limit too, but the early check avoids the round-trip when the caller already knows the payload is too large.
+
+- **Response decoder hardening (Wave 13 conformance fix).** Added `KnownDoneReason` literal type (`'stop' | 'length' | 'load' | 'unload'`) and `isKnownDoneReason()` type guard so callers can narrow `done_reason` from `string | undefined` without risking `TypeError` on undefined access — the failure mode flagged in CI run #36962280416. The `done_reason` field on `ChatResponse` / `GenerateResponse` remains `string | undefined` for forward-compat with future upstream additions; the type guard provides opt-in narrowing.
+
 ## [1.8.0] - 2026-10-02
 
 - **Contract execution completion (Waves 12-16).** The SDK's contract-first architecture is now fully executable: every operation in the canonical IR is represented, generated, typed, and runtime-enforced with no `Record<string, unknown>` escape hatches on the generated surface.

package/README.md

@@ -12,14 +12,18 @@
 
 - 🚀 **Native Web Standards**: Built on native `fetch` and Web Streams. Zero external HTTP dependencies.
 - 🧠 **Reasoning & Thinking Tokens**: First-class support for reasoning models (`qwen3:8b`, `deepseek-r1:8b`) via the native `think` parameter, with discrete `thinking` and `token` streaming events, plus `logprobs`/`top_logprobs` for token-level confidence scoring.
-- 🖼️ **Multimodal / Vision Input**: `images` on `Message`/`generate()` accepts base64 strings or raw `Uint8Array` bytes (auto-encoded) for vision models like `llava` or `qwen2.5vl`.
+- 🖼️ **Multimodal / Vision Input**: `images` on `Message`/`generate()` is a universal resolver — pass raw base64 strings, `data:image/...;base64,` data URIs, `http(s)://` URLs (fetched), local file paths (`.png`/`.jpg`/`.webp`/…, read via `node:fs` on Node), or raw `Buffer`/`Uint8Array` bytes — everything is normalized to the raw base64 Ollama's REST API expects, matching the official SDK vision convention.
 - 🎯 **Zod-Powered Structured Outputs**: Strictly typed schema enforcement via `chatWithSchema` and `generateWithSchema` with resilient markdown JSON parsing.
 - 🛠️ **Autonomous Agent & Tool Calling**: Multi-turn agent loop (`Agent`) with automated tool execution, parameter validation, and self-correcting error recovery.
 - 🌐 **High Availability & Failover**: Multi-endpoint registry with priority routing, circuit breaker failover, active health checks, and per-endpoint `models` allow-lists for routing several model-specific API keys through one client.
 - 🔌 **Model Context Protocol (MCP)**: First-class, transport-neutral `McpBridge` for converting MCP tool descriptors into Ollama function definitions and registering executable MCP-backed tools.
 - 📚 **Full Model Lifecycle**: `pullModel`, `pushModel`, `createModel`, `copyModel`, `deleteModel`, `listModels`, `showModel`, and `ps()` (currently loaded models) — full parity with Ollama's model management API.
 - 🔎 **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`.
-- 🌉 **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.
+- 💳 **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.
+- 🛑 **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}`).
 - 🌊 **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.
@@ -241,6 +245,105 @@ console.log(res.prompt_eval_count, res.prompt_eval_cached_count);
 console.log(res.prompt_eval_cached_count ?? 0);
 ```
 
+### KV-Cache-Aware Conversation Sessions
+
+Ollama reuses the model's KV cache across turns by **prompt prefix matching** — anything that mutates the prefix (changing the system prompt, injecting per-call timestamps, reordering past turns) invalidates the whole cache and forces a full re-evaluation. `client.session()` makes the cache-friendly structure the default: a system prompt pinned at construction, an append-only frozen history, and per-turn options that never touch the prefix.
+
+```typescript
+const session = client.session('llama3.1', 'You are a concise assistant.');
+
+// Ergonomic path — just the reply text
+await session.send('Hi!');
+
+// Detailed path — per-turn KV-cache statistics + raw response
+const turn = await session.sendTurn('Why is the sky blue?');
+console.log(turn.cache);
+// { cachedTokens: 48, evaluatedTokens: 6, hitRate: 0.89 }
+
+// Cumulative view across the whole session
+console.log(session.cacheStats);
+// { turns: 2, cachedTokens: 48, evaluatedTokens: 54, totalPromptTokens: 102, hitRate: 0.47 }
+
+session.reset(); // back to system-prompt-only, stats zeroed
+session.getMessages(); // defensive copy of the frozen history
+```
+
+Note the hit-rate denominator: when the _entire_ prompt hits the cache, Ollama reports `prompt_eval_count: 0` — the session's `hitRate` adds both counters so the best case scores `1`, not `0`.
+
+### OpenAI Responses API (dual-mode)
+
+`client.responses.create()` gives migrating OpenAI code a small, familiar surface (`model`, `input`, `instructions`, `tools`, `temperature`, `top_p`, `max_output_tokens`, `reasoning_effort`, `think`) with **dual-mode transport**: the native `POST /v1/responses` endpoint is preferred (Ollama ≥ v0.13.3), and a `404` from older servers transparently re-issues the request through `/api/chat` — `instructions` mapped to a system message, the reply mapped back into the Responses shape. The result's `transport` field records which path served it.
+
+```typescript
+const res = await client.responses.create({
+  model: 'gpt-oss:20b',
+  input: 'Explain KV caches in one paragraph.',
+  instructions: 'Be precise.',
+  max_output_tokens: 256,
+  reasoning_effort: 'medium',
+});
+
+console.log(res.output_text);
+console.log(res.usage); // { input_tokens, output_tokens, total_tokens }
+console.log(res.transport); // 'native' | 'chat-adapter'
+
+// Streaming variant — simplified text/thinking deltas + final response
+for await (const event of client.responses.stream({ model: 'qwen3', input: 'Tell me a haiku.' })) {
+  if (event.type === 'text_delta') process.stdout.write(event.delta);
+  else if (event.type === 'done') console.log('\n', event.response.usage);
+}
+```
+
+Ollama implements the Responses API **non-statefully** — `previous_response_id` and `conversation` don't exist, so send the full conversation in `input` every call (or use `ConversationSession` to manage it). For the full OpenAI-shaped surface (raw `output` items, SSE event objects), use `client.openai.responses()`.
+
+### Context-Window Safety (silent-truncation guard)
+
+With `num_ctx` unset, Ollama loads the model with a conservative default window (commonly 2048–4096 tokens) and **silently truncates** prompts that don't fit — the model simply loses the top of the conversation with no error. The client estimates the prompt size before every `chat`/`generate` call and surfaces the risk:
+
+```typescript
+const client = new OllamaClient({
+  // Make the window explicit on every request that omits options.num_ctx
+  defaultContextLength: 8192,
+
+  // 'warn' (default): log through `logger` and send anyway
+  // 'throw': reject client-side with OllamaClientError before anything hits the wire
+  onContextOverflow: 'warn',
+});
+
+// Warnings fire when the estimate crosses 90% of the effective window:
+// "OllamaClient.chat(): estimated prompt size ~1900 tokens is close to or
+//  beyond the request's context window (num_ctx=2048). The server will
+//  likely silently truncate …"
+```
+
+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`).
+
+### 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:
+
+```typescript
+// Content-addressed digest: SHA-256 -> "sha256:<64 lowercase hex>"
+const digest = await client.models.computeBlobDigest(ggufBytes);
+
+// HEAD-check + upload (skips the POST when the blob already exists)
+const { digest, alreadyExisted } = await client.models.createBlobFromData(ggufBytes);
+const upload = await client.models.createBlobFromFile('/models/my-model.gguf');
+// -> { digest: 'sha256:…', alreadyExisted: false, fileName: 'my-model.gguf' }
+
+// One-shot: upload every GGUF shard, then POST /api/create with files: {name: digest}
+await client.models.createModelFromGguf('my-model', '/models/my-model.gguf', {
+  template: '{{ .Prompt }}',
+  parameters: { temperature: 0.7 },
+});
+
+// Split GGUFs: pass every shard
+await client.models.createModelFromGguf('my-model', [
+  '/models/model-00001-of-00002.gguf',
+  '/models/model-00002-of-00002.gguf',
+]);
+```
+
 ### Token Log Probabilities (`logprobs`)
 
 Set `logprobs: true` (optionally with `top_logprobs`) on `chat()`/`generate()` to get per-token log probabilities back — useful for confidence scoring, speculative decoding, or agent routing decisions.
@@ -261,27 +364,62 @@ for (const entry of res.logprobs ?? []) {
 
 ### Multimodal / Vision Input
 
-`images` on a `Message` (or on `generate()`'s top-level request) accepts base64-encoded strings or raw `Uint8Array` bytes — `Uint8Array` entries are base64-encoded automatically before the request is sent.
+`images` on a `Message` (or on `generate()`'s top-level request) is a **universal vision resolver** — every polymorphic form is normalized to the raw base64 string Ollama's REST API expects (no `data:image/...;base64,` URI prefixes ever reach the wire):
 
 ```typescript
-import { readFile } from 'node:fs/promises';
+// 1. Local file paths (Node.js — read via dynamically-imported node:fs)
+const res = await client.chatText({
+  model: 'llava',
+  messages: [
+    {
+      role: 'user',
+      content: 'What is in this image?',
+      images: ['./cat.png'],
+    },
+  ],
+});
 
-const imageBytes = await readFile('./cat.png'); // Buffer, a Uint8Array subclass
+// 2. Data URIs — the header is stripped automatically
+await client.chat({
+  model: 'llava',
+  messages: [
+    {
+      role: 'user',
+      content: 'Describe this.',
+      images: ['data:image/png;base64,iVBORw0KGgo...'],
+    },
+  ],
+});
 
-const res = await client.chatText({
+// 3. Web URLs — fetched and encoded
+await client.chat({
   model: 'llava',
-  messages: [{ role: 'user', content: 'What is in this image?', images: [imageBytes] }],
+  messages: [{ role: 'user', content: 'OCR this.', images: ['https://example.com/receipt.png'] }],
 });
-console.log(res);
 
-// Base64 strings work too, unchanged:
-const base64Res = await client.generateText({
+// 4. Raw bytes — Buffer / Uint8Array, base64-encoded automatically
+import { readFile } from 'node:fs/promises';
+await client.chat({
+  model: 'llava',
+  messages: [
+    {
+      role: 'user',
+      content: 'What is in this image?',
+      images: [await readFile('./cat.png')],
+    },
+  ],
+});
+
+// 5. Plain base64 strings — passed through unchanged
+await client.generateText({
   model: 'llava',
   prompt: 'Describe this image.',
   images: ['iVBORw0KGgoAAAANSUhEUgAA...'],
 });
 ```
 
+The resolver is also exported standalone for custom pipelines: `resolveImageInput(input)` (single) and `resolveImages(images)` (batch, parallel). In browsers/edge runtimes, file-path strings throw a descriptive error (no `node:fs`) — read the file yourself and pass the bytes.
+
 ### Structured Outputs with Zod
 
 ```typescript
@@ -367,6 +505,39 @@ console.log(page.title, page.content.slice(0, 200));
 
 These two methods don't participate in the multi-endpoint failover below — there's only ever the one cloud host to call — but they do use the same default `timeoutMs` and retry policy as everything else.
 
+### Cloud Usage & Balance (Ollama Cloud account)
+
+`usage`/`balance` wrap Ollama's **hosted account endpoints** (`GET https://ollama.com/api/usage` and `/api/balance`) — the same fixed Ollama Cloud service and API-key requirements as `webSearch`/`webFetch` above, so everything said there about auth, timeouts, and retry applies identically here:
+
+```typescript
+const client = new OllamaClient({
+  baseUrl: 'http://localhost:11434', // local inference — unrelated to the calls below
+  apiKey: process.env.OLLAMA_API_KEY, // required for usage/balance specifically
+});
+
+// Usage for the last 24 hours, bucketed hourly (omit options for the server
+// defaults: range='7d', scope='self'). Team scope requires a team admin.
+const usage = await client.usage({ range: '24h' });
+console.log(usage.totals.request_count, usage.totals.usage_usd, usage.totals.cached_input_tokens);
+for (const bucket of usage.buckets) {
+  if (bucket.partial) continue; // the current hour — still in progress
+  console.log(bucket.from, bucket.request_count);
+}
+
+// Remaining credits. `included` is either the plan-period credits object
+// (`balance_usd`/`allowance_usd`/`period`) or, on legacy plans, the
+// session/weekly percentage-limits shape — discriminated by the response.
+const balance = await client.balance();
+if ('balance_usd' in balance.included) {
+  console.log(`included: $${balance.included.balance_usd} of $${balance.included.allowance_usd}`);
+} else {
+  console.log(`session limit: ${balance.included.session.remaining_percent}% remaining`);
+}
+console.log(`purchased: $${balance.purchased.balance_usd}`);
+```
+
+Both endpoints are rate-limited to 10 requests/minute per user (429 responses carry `Retry-After`); polling about once a minute is the recommended cadence.
+
 ### Autonomous Agent & Tool Calling
 
 ```typescript

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

@@ -1,4 +1,4 @@
-import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, ab as SseEvent, w as OllamaClientError } from './runtime-C6UYtBRB.js';
+import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, ae as SseEvent, x as OllamaClientError } from './runtime-C3rfpkZw.js';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
@@ -139,6 +139,8 @@ interface CreateRequest {
     readonly draft_quantize?: string | undefined;
     /** Minimum Ollama version required by the model */
     readonly requires?: string | undefined;
+    /** Capabilities to add without removing inherited or inferred capabilities (e.g. `decision` for compatible decision models) */
+    readonly capabilities?: readonly string[] | undefined;
     /** Stream status updates */
     readonly stream?: boolean | undefined;
 }
@@ -342,7 +344,7 @@ interface ModelSummary {
         /** Primary model family (for example `llama`) */
         readonly family?: string | undefined;
         /** All families the model belongs to, when applicable */
-        readonly families?: readonly string[] | undefined;
+        readonly families?: readonly string[] | null | undefined;
         /** Approximate parameter count label (for example `7B`, `13B`) */
         readonly parameter_size?: string | undefined;
         /** Quantization level used (for example `Q4_0`) */

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

@@ -1,4 +1,4 @@
-import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, ab as SseEvent, w as OllamaClientError } from './runtime-DTmUeU6K.cjs';
+import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, ae as SseEvent, x as OllamaClientError } from './runtime-D2W9TfCJ.cjs';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
@@ -139,6 +139,8 @@ interface CreateRequest {
     readonly draft_quantize?: string | undefined;
     /** Minimum Ollama version required by the model */
     readonly requires?: string | undefined;
+    /** Capabilities to add without removing inherited or inferred capabilities (e.g. `decision` for compatible decision models) */
+    readonly capabilities?: readonly string[] | undefined;
     /** Stream status updates */
     readonly stream?: boolean | undefined;
 }
@@ -342,7 +344,7 @@ interface ModelSummary {
         /** Primary model family (for example `llama`) */
         readonly family?: string | undefined;
         /** All families the model belongs to, when applicable */
-        readonly families?: readonly string[] | undefined;
+        readonly families?: readonly string[] | null | undefined;
         /** Approximate parameter count label (for example `7B`, `13B`) */
         readonly parameter_size?: string | undefined;
         /** Quantization level used (for example `Q4_0`) */

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

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

package/dist/{compose-DS-UWFx8.d.cts → compose-Dj6FdF2n.d.cts}

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

package/dist/generated-api.cjs

@@ -1,6 +1,25 @@
 'use strict';
 
 // src/generated/api/operations.ts
+var balanceOp = {
+  operationId: "balance",
+  method: "GET",
+  path: "/api/balance",
+  response: { $ref: "#/schemas/BalanceResponse" },
+  environment: { local: false, cloud: true },
+  host: "https://ollama.com",
+  transport: { mode: "json", streaming: false },
+  capabilities: {},
+  status: { documented: true },
+  domain: "native",
+  notes: [
+    "Cloud-only account endpoint \u2014 targets https://ollama.com, not the local Ollama server.",
+    "Requires an Ollama Cloud API key (set via OllamaClient credentials).",
+    "Takes no parameters. For usage history see the usage operation.",
+    "Rate limited to 10 requests/minute per user; 429 responses carry a Retry-After header.",
+    "Use OllamaClient.balance() \u2014 the generated NativeApi class does not expose this operation."
+  ]
+};
 var blobsOp = {
   operationId: "blobs",
   method: "HEAD",
@@ -208,6 +227,25 @@ var tagsOp = {
   status: { documented: true },
   domain: "native"
 };
+var usageOp = {
+  operationId: "usage",
+  method: "GET",
+  path: "/api/usage",
+  response: { $ref: "#/schemas/UsageResponse" },
+  environment: { local: false, cloud: true },
+  host: "https://ollama.com",
+  transport: { mode: "json", streaming: false },
+  capabilities: {},
+  status: { documented: true },
+  domain: "native",
+  notes: [
+    "Cloud-only account endpoint \u2014 targets https://ollama.com, not the local Ollama server.",
+    "Requires an Ollama Cloud API key (set via OllamaClient credentials).",
+    "Query parameters (not modeled by the generated runtime): range = 24h | 7d | 30d (server default 7d), scope = self | team (server default self; team scope requires a team admin).",
+    "Rate limited to 10 requests/minute per user; 429 responses carry a Retry-After header.",
+    "Use OllamaClient.usage() \u2014 the generated NativeApi class does not expose this operation."
+  ]
+};
 var versionOp = {
   operationId: "version",
   method: "GET",
@@ -344,6 +382,7 @@ var anthropicMessagesOp = {
   ]
 };
 var allOperations = [
+  balanceOp,
   blobsOp,
   chatOp,
   copyOp,
@@ -358,6 +397,7 @@ var allOperations = [
   showOp,
   systemOneOp,
   tagsOp,
+  usageOp,
   versionOp,
   webFetchOp,
   webSearchOp,
@@ -375,7 +415,6 @@ var NativeApi = class {
   constructor(runtime) {
     this.runtime = runtime;
   }
-  runtime;
   blobs(digest, options) {
     return this.runtime.invoke({
       operation: blobsOp,
@@ -477,7 +516,6 @@ var OpenAIApi = class {
   constructor(runtime) {
     this.runtime = runtime;
   }
-  runtime;
   openaiChatCompletions(request) {
     return this.runtime.invoke({
       operation: openaiChatCompletionsOp,
@@ -524,7 +562,6 @@ var AnthropicApi = class {
   constructor(runtime) {
     this.runtime = runtime;
   }
-  runtime;
   anthropicMessages(request) {
     return this.runtime.invoke({
       operation: anthropicMessagesOp,
@@ -538,6 +575,7 @@ exports.NativeApi = NativeApi;
 exports.OpenAIApi = OpenAIApi;
 exports.allOperations = allOperations;
 exports.anthropicMessages = anthropicMessagesOp;
+exports.balance = balanceOp;
 exports.blobs = blobsOp;
 exports.chat = chatOp;
 exports.copy = copyOp;
@@ -558,6 +596,7 @@ exports.push = pushOp;
 exports.show = showOp;
 exports.systemOne = systemOneOp;
 exports.tags = tagsOp;
+exports.usage = usageOp;
 exports.version = versionOp;
 exports.webFetch = webFetchOp;
 exports.webSearch = webSearchOp;