@nemesis-oss/ollama-sdk 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [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

@@ -24,11 +24,13 @@
 - 💬 **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}`).
+- 🧵 **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.
 - 🌊 **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).
 
 ---
@@ -462,6 +464,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)):
@@ -962,6 +989,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 +1414,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-CPaoxeLX.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, ae as SseEvent, x as OllamaClientError } from './runtime-BV9SK_cf.js';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.

package/dist/{anthropic-BIh45UXj.d.cts → anthropic-DuE8M6Tz.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, ae as SseEvent, x as OllamaClientError } from './runtime-BsdBbuOv.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-DuE8M6Tz.cjs';
+export { N as NativeApi } from './anthropic-DuE8M6Tz.cjs';
+import { O as OllamaRuntime } from './runtime-BsdBbuOv.cjs';
+export { a as OperationDefinition } from './runtime-BsdBbuOv.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-CPaoxeLX.js';
+export { N as NativeApi } from './anthropic-CPaoxeLX.js';
+import { O as OllamaRuntime } from './runtime-BV9SK_cf.js';
+export { a as OperationDefinition } from './runtime-BV9SK_cf.js';
+import './types-BtQexFpT.js';
 import 'zod';
 
 /**

package/dist/generated-runtime.d.cts

@@ -1,6 +1,6 @@
-export { I as InvokeRequest, O as OllamaRuntime, b as OllamaRuntimeOptions, a as OperationDefinition, S as SchemaRef } from './runtime-D2W9TfCJ.cjs';
+export { I as InvokeRequest, O as OllamaRuntime, b as OllamaRuntimeOptions, a as OperationDefinition, S as SchemaRef } from './runtime-BsdBbuOv.cjs';
 import { z } from 'zod';
-import './types-DVcX_zMp.cjs';
+import './types-BtQexFpT.cjs';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.

package/dist/generated-runtime.d.ts

@@ -1,6 +1,6 @@
-export { I as InvokeRequest, O as OllamaRuntime, b as OllamaRuntimeOptions, a as OperationDefinition, S as SchemaRef } from './runtime-C3rfpkZw.js';
+export { I as InvokeRequest, O as OllamaRuntime, b as OllamaRuntimeOptions, a as OperationDefinition, S as SchemaRef } from './runtime-BV9SK_cf.js';
 import { z } from 'zod';
-import './types-DVcX_zMp.js';
+import './types-BtQexFpT.js';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.

package/dist/index.cjs

@@ -4474,6 +4474,130 @@ function contextWarningMessage(check2, kind) {
   return `${where}: estimated prompt size ${estimate} outright exceeds Ollama's conservative server-default context window (${OLLAMA_FALLBACK_CONTEXT_LENGTH}\u20134096 tokens when \`num_ctx\` is unset \u2014 model-dependent). Unless the model's default is larger, the server will silently truncate the top of the conversation \u2014 the model loses earlier turns with no error. Set \`options.num_ctx\` (or the client's \`defaultContextLength\`) to an explicit window to make truncation visible and controllable. Estimates are heuristic (\xB120\u201330%); see \`estimateTokens\`.`;
 }
 
+// src/embed-batch.ts
+var DEFAULT_EMBED_BATCH_SIZE = 32;
+var DEFAULT_EMBED_CONCURRENCY = 3;
+function findOversizedEmbedInputs(input, contextLength) {
+  const oversized = [];
+  for (let index = 0; index < input.length; index++) {
+    const text = input[index];
+    if (text === void 0) continue;
+    const estimate = estimateTokens(text);
+    if (estimate > contextLength) {
+      oversized.push({ index, estimate });
+    }
+  }
+  return oversized;
+}
+function embedBatchOverflowMessage(oversized, totalInputs, contextLength, truncateFalse) {
+  const shown = oversized.slice(0, 5).map((entry) => `#${entry.index} (~${entry.estimate} tokens)`);
+  const elided = oversized.length > 5 ? `, +${oversized.length - 5} more` : "";
+  const outcome = truncateFalse ? "the server will reject them (`truncate: false`)" : "Ollama will silently truncate them, producing degraded vectors";
+  return `embedBatch: ${oversized.length} of ${totalInputs} input strings exceed the ${contextLength}-token context window (${shown.join(", ")}${elided}). ${outcome}. Raise \`options.num_ctx\`, pre-split long inputs, or set \`truncate: true\` explicitly to acknowledge truncation.`;
+}
+function assertPositiveInteger(value, field) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new OllamaClientError(
+      `embedBatch: \`${field}\` must be a positive integer (got ${value}).`,
+      { code: "invalid_request" }
+    );
+  }
+}
+async function batchEmbed(client, options) {
+  const { model, input } = options;
+  const batchSize = options.batchSize ?? DEFAULT_EMBED_BATCH_SIZE;
+  const concurrency = options.concurrency ?? DEFAULT_EMBED_CONCURRENCY;
+  assertPositiveInteger(batchSize, "batchSize");
+  assertPositiveInteger(concurrency, "concurrency");
+  if (input.length === 0) {
+    return { model, embeddings: [], batchCount: 0 };
+  }
+  const batches = [];
+  for (let start = 0; start < input.length; start += batchSize) {
+    batches.push(input.slice(start, start + batchSize));
+  }
+  const embeddings = new Array(input.length);
+  const controller = new AbortController();
+  const propagateExternalAbort = () => {
+    controller.abort(options.signal?.reason);
+  };
+  if (options.signal) {
+    if (options.signal.aborted) {
+      propagateExternalAbort();
+    } else {
+      options.signal.addEventListener("abort", propagateExternalAbort, { once: true });
+    }
+  }
+  let nextBatch = 0;
+  let completedBatches = 0;
+  let failure;
+  const worker = async () => {
+    for (; ; ) {
+      if (controller.signal.aborted) {
+        throw failure?.error ?? new OllamaAbortError("Embed batch aborted");
+      }
+      const batchIndex = nextBatch;
+      nextBatch++;
+      if (batchIndex >= batches.length) return;
+      const batch = batches[batchIndex];
+      if (!batch) return;
+      try {
+        const request = {
+          model,
+          input: batch,
+          ...options.truncate !== void 0 ? { truncate: options.truncate } : {},
+          ...options.dimensions !== void 0 ? { dimensions: options.dimensions } : {},
+          ...options.keep_alive !== void 0 ? { keep_alive: options.keep_alive } : {},
+          ...options.options !== void 0 ? { options: options.options } : {},
+          ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {},
+          signal: controller.signal
+        };
+        const response = await client.embed(request);
+        if (response.embeddings.length !== batch.length) {
+          throw new OllamaClientError(
+            `embedBatch: server returned ${response.embeddings.length} embeddings for a batch of ${batch.length} inputs (batch ${batchIndex}).`,
+            { code: "invalid_response" }
+          );
+        }
+        const offset = batchIndex * batchSize;
+        for (let j = 0; j < batch.length; j++) {
+          embeddings[offset + j] = response.embeddings[j];
+        }
+        completedBatches++;
+        options.onBatchComplete?.(completedBatches, batches.length);
+      } catch (error) {
+        if (!failure) {
+          failure = { error };
+          controller.abort(error);
+          throw error;
+        }
+        throw failure.error;
+      }
+    }
+  };
+  try {
+    const workerCount = Math.min(concurrency, batches.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  } finally {
+    if (options.signal) {
+      options.signal.removeEventListener("abort", propagateExternalAbort);
+    }
+  }
+  for (let i = 0; i < embeddings.length; i++) {
+    if (embeddings[i] === void 0) {
+      throw new OllamaClientError(
+        `embedBatch: internal invariant violated \u2014 no embedding produced for input #${i}.`,
+        { code: "invalid_response" }
+      );
+    }
+  }
+  return {
+    model,
+    embeddings,
+    batchCount: batches.length
+  };
+}
+
 // src/generated/api/operations.ts
 var blobsOp = {
   operationId: "blobs",
@@ -4998,6 +5122,14 @@ var OllamaClient = class {
   contextWarningThreshold;
   /** Configured overflow policy — `'warn'` (default) or `'throw'`. */
   onContextOverflow;
+  /**
+   * Controllers for every in-flight request and active stream managed by this
+   * client — see {@link OllamaClient.destroy} and {@link createRequestScope}.
+   * Entries live for exactly as long as the underlying work does: until the
+   * response settles (requests) or the stream's `finalResult` settles
+   * (streams, via `executeWithFailover`'s `holdUntil` release path).
+   */
+  activeRequests = /* @__PURE__ */ new Set();
   constructor(config = {}) {
     this.cloudApiKey = resolveApiKey(config.apiKey);
     const defaultBaseUrl = resolveBaseUrl(config.baseUrl);
@@ -5162,6 +5294,39 @@ var OllamaClient = class {
     }
     return { ...options, num_ctx: this.defaultContextLength };
   }
+  /**
+   * Creates the per-request abort scope registered with {@link destroy}:
+   * a controller that fires when the caller's `signal` aborts OR when
+   * `destroy()` runs, whichever comes first. `dispose()` removes the
+   * registration when the work it guards settles — for plain requests when
+   * the response settles, for streams when `finalResult` settles (the same
+   * moment `executeWithFailover`'s `holdUntil` releases the endpoint slot),
+   * so a destroy() can tear down a stream mid-consumption but never outlives
+   * one that already finished.
+   */
+  createRequestScope(userSignal) {
+    const controller = new AbortController();
+    const propagateUserAbort = () => {
+      controller.abort(userSignal?.reason);
+    };
+    let detach;
+    if (userSignal) {
+      if (userSignal.aborted) {
+        propagateUserAbort();
+      } else {
+        userSignal.addEventListener("abort", propagateUserAbort, { once: true });
+        detach = () => userSignal.removeEventListener("abort", propagateUserAbort);
+      }
+    }
+    this.activeRequests.add(controller);
+    return {
+      signal: controller.signal,
+      dispose: () => {
+        detach?.();
+        this.activeRequests.delete(controller);
+      }
+    };
+  }
   /**
    * Fail-fast guard for `format` (structured output) requests: throws before any network
    * call if the candidate endpoint is inferred as Ollama Cloud, which does not currently
@@ -5178,7 +5343,8 @@ var OllamaClient = class {
     }
   }
   async executeWithFailover(operation, options) {
-    const timeout = createTimeoutSignal(options?.timeoutMs ?? this.timeoutMs, options?.signal);
+    const scope = this.createRequestScope(options?.signal);
+    const timeout = createTimeoutSignal(options?.timeoutMs ?? this.timeoutMs, scope.signal);
     const requestId = createLogicalRequestId();
     let deferTimeoutCancel = false;
     try {
@@ -5257,6 +5423,7 @@ var OllamaClient = class {
             if (holdPromise) {
               void holdPromise.catch(() => void 0).finally(() => {
                 timeout.cancel();
+                scope.dispose();
                 this.registry.release(endpoint.name);
               });
             } else {
@@ -5267,7 +5434,10 @@ var OllamaClient = class {
         throw lastError ?? new Error("No healthy Ollama endpoints available");
       }
     } finally {
-      if (!deferTimeoutCancel) timeout.cancel();
+      if (!deferTimeoutCancel) {
+        timeout.cancel();
+        scope.dispose();
+      }
     }
   }
   async chat(req) {
@@ -5427,6 +5597,58 @@ var OllamaClient = class {
     const res = await this.embed({ model, input });
     return res.embeddings;
   }
+  /**
+   * Batch-constrained, order-preserving embedding generation for large
+   * corpora — the safe building block for RAG/vector-index ingestion at
+   * scale. Splits `input` into `batchSize` slices and embeds them through
+   * {@link embed} with at most `concurrency` batches in flight (defaults:
+   * 32 × 3), so `Promise.all`-style floods that OOM local daemons and
+   * saturate `OLLAMA_MAX_QUEUE` can't happen by accident. Fail-fast: the
+   * first batch error aborts every sibling in-flight batch and rejects the
+   * whole operation with the original error.
+   *
+   * Before any request is sent, `defaultContextLength` is injected as
+   * `num_ctx` (same as chat/generate) and each input string's token estimate
+   * is checked against the resolved window: Ollama silently truncates
+   * oversized embedding inputs by default, so the client warns (or throws,
+   * under `onContextOverflow: 'throw'`) with the offending indexes — see
+   * `src/embed-batch.ts` for the exact trip point (no margin: an embedding
+   * prompt IS the whole input).
+   *
+   * ```ts
+   * const { embeddings, batchCount } = await client.embedBatch({
+   *   model: 'nomic-embed-text:latest',
+   *   input: corpus,                 // e.g. 50k chunks
+   *   batchSize: 32,                 // inputs per /api/embed request
+   *   concurrency: 3,                // batches in flight
+   *   onBatchComplete: (done, total) => progress.log(`${done}/${total}`),
+   * });
+   * // embeddings[i] always corresponds to corpus[i]
+   * ```
+   */
+  async embedBatch(options) {
+    const resolvedOptions = this.injectDefaultContextLength(options.options);
+    const contextLength = resolvedOptions?.num_ctx;
+    if (contextLength !== void 0) {
+      const oversized = findOversizedEmbedInputs(options.input, contextLength);
+      if (oversized.length > 0) {
+        const message = embedBatchOverflowMessage(
+          oversized,
+          options.input.length,
+          contextLength,
+          options.truncate === false
+        );
+        if (this.onContextOverflow === "throw") {
+          throw new OllamaClientError(message, { code: "context_overflow" });
+        }
+        this.logger.warn(message);
+      }
+    }
+    return batchEmbed(
+      this,
+      resolvedOptions === options.options ? options : { ...options, options: resolvedOptions }
+    );
+  }
   /**
    * @deprecated Ollama's `/api/embeddings` endpoint has been superseded by `/api/embed`
    * (exposed here as {@link OllamaClient.embed}), which additionally supports batch
@@ -5596,10 +5818,12 @@ var OllamaClient = class {
   async executeCloudRequest(operation, options) {
     var _stack = [];
     try {
-      const timeout = createTimeoutSignal(options.timeoutMs ?? this.timeoutMs, options.signal);
+      const scope = this.createRequestScope(options.signal);
+      const timeout = createTimeoutSignal(options.timeoutMs ?? this.timeoutMs, scope.signal);
       const _timeout = __using(_stack, {
         [Symbol.dispose]() {
           timeout.cancel();
+          scope.dispose();
         }
       });
       const requestId = createLogicalRequestId();
@@ -5660,6 +5884,34 @@ var OllamaClient = class {
   endpointStatus() {
     return this.registry.status();
   }
+  /**
+   * Immediately aborts every in-flight request and active stream managed by
+   * this client — the clean teardown path for short-lived processes, CLI
+   * runners, and `node:worker_threads` tasks where dangling fetch bodies,
+   * unconsumed stream readers, or queued capacity waiters would otherwise
+   * keep the event loop (and thus the thread/process) alive.
+   *
+   * Every aborted operation rejects with an {@link OllamaAbortError}
+   * (`code: 'aborted'`) carrying `reason` as its message — including requests
+   * still queued behind `maxConcurrentPerEndpoint`, not just dispatched ones.
+   * Streams reject their `finalResult` and release their endpoint slots.
+   *
+   * Idempotent: calling it again (or on a client with nothing in flight)
+   * is a no-op that returns `0`. The client remains usable afterward —
+   * `destroy()` is a drain, not a permanent disable; callers that want a
+   * permanently-dead client should discard the instance.
+   *
+   * @returns the number of in-flight operations that were aborted.
+   */
+  destroy(reason = "Ollama client destroyed") {
+    const controllers = [...this.activeRequests];
+    const cause = new OllamaAbortError(reason);
+    for (const controller of controllers) {
+      controller.abort(cause);
+    }
+    this.activeRequests.clear();
+    return controllers.length;
+  }
   // --- Compatibility Adapters ---
   get openai() {
     const ep = this.registry.candidates()[0];
@@ -6821,6 +7073,8 @@ exports.ConversationSession = ConversationSession;
 exports.DEFAULT_BACKOFF = DEFAULT_BACKOFF;
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
 exports.DEFAULT_CONTEXT_WARNING_THRESHOLD = DEFAULT_CONTEXT_WARNING_THRESHOLD;
+exports.DEFAULT_EMBED_BATCH_SIZE = DEFAULT_EMBED_BATCH_SIZE;
+exports.DEFAULT_EMBED_CONCURRENCY = DEFAULT_EMBED_CONCURRENCY;
 exports.DEFAULT_FAILOVER_CODES = DEFAULT_FAILOVER_CODES;
 exports.DEFAULT_FETCH_BACKOFF_CONFIG = DEFAULT_FETCH_BACKOFF_CONFIG;
 exports.DEFAULT_RETRY_CONFIG = DEFAULT_RETRY_CONFIG;
@@ -6882,6 +7136,7 @@ exports.ToolCallAccumulator = ToolCallAccumulator;
 exports.ToolRegistry = ToolRegistry;
 exports.addSpanEvent = addSpanEvent;
 exports.applySkill = applySkill;
+exports.batchEmbed = batchEmbed;
 exports.calculateBackoff = calculateBackoff;
 exports.checkChatContext = checkChatContext;
 exports.checkEndpointHealth = checkEndpointHealth;
@@ -6894,6 +7149,7 @@ exports.createOllamaCloudFreeTierQuota = createOllamaCloudFreeTierQuota;
 exports.createTimeoutSignal = createTimeoutSignal;
 exports.defineTool = defineTool;
 exports.detectModelCapabilities = detectModelCapabilities;
+exports.embedBatchOverflowMessage = embedBatchOverflowMessage;
 exports.encodeImage = encodeImage;
 exports.estimateChatRequestTokens = estimateChatRequestTokens;
 exports.estimateGenerateRequestTokens = estimateGenerateRequestTokens;
@@ -6901,6 +7157,7 @@ exports.estimateSystemOneRequestBytes = estimateSystemOneRequestBytes;
 exports.estimateTokens = estimateTokens;
 exports.extractUsage = extractUsage;
 exports.fetchWithBackoff = fetchWithBackoff;
+exports.findOversizedEmbedInputs = findOversizedEmbedInputs;
 exports.imageStringNeedsResolution = imageStringNeedsResolution;
 exports.inferRuntimeMode = inferRuntimeMode;
 exports.isKeepAliveSugar = isKeepAliveSugar;